docs: AWS deployment architecture proposals (subdomain and single-host tenant-picker variants)

[iliyan-velichkov]

Summary

Documentation only — two sibling architecture proposals for deploying a multitenant Dirigible application on AWS, both right-sized to one production unit (~50–100 tenants) and designed independently of the docs/aws-multitenancy-research branch (each records where it agrees/differs).

1. AWS_DEPLOYMENT_PROPOSAL.md — subdomain per tenant

• Compute: ECS Fargate, desiredCount=1, stop-then-start deploys. The runtime is single-writer by construction (embedded ActiveMQ vm:// broker holding a JDBC lock on SystemDB, node-local synchronizer effects, LocalRepository) — the availability consequence (~99.5% SLO) is stated honestly instead of worked around.
• Data: RDS PostgreSQL Multi-AZ with the shipped schema-per-tenant provisioning; documents on S3 (engine-cms-s3); content baked into the image with publishing disabled; optional internal authoring instance as the In-System-Programming security boundary.
• Identity: ONE Cognito user pool (one identity = same credentials in every tenant) and one confidential app client per tenant — decided on merit in §4.2 against the single-shared-client alternative (100-callback hard ceiling at the design capacity, no tenant signal for the pre-token Lambda, multi-tenant bearer tokens with app-side-only denial). The shipped security-client-registration module is explicitly not a design input.
• Cross-tenant login: membership and roles as prefixed Cognito groups (t:<subdomain>:<role>); a pre-token-generation Lambda scopes every token to its tenant (cognito:groups = roles-here-only + a dirigible:tenant audience claim). One interactive sign-in, silent SSO into other tenants, different roles in each.
• Fork changes: seven must-fix items with file:line anchors, plus four follow-ups; onboarding/offboarding runbooks, hardening checklist, operations, cost ballpark (~$700/month), how-it-grows, and six pre-go-live hypotheses flagged rather than asserted.

2. AWS_SINGLE_HOST_TENANT_PICKER_PROPOSAL.md — no subdomains, in-app tenant picker

The variant for changed requirements: one host, one login, and the user changes the current tenant from a picker in the UI, holding different roles in each. Everything below the identity layer is inherited from proposal 1 unchanged.

• Dropping subdomains removes the Host header as the tenant signal, and the picker means the tenant is chosen after login and changes without re-auth — so the active tenant becomes server-side session state, and the default-tenant fallback is removed for authenticated traffic (no selection → picker page, never silent default).
• The token carries the full membership graph as prefixed groups, parsed at login into a membership map with zero authorities; POST /services/core/security/tenants/current validates membership, rebuilds the session's authorities to the picked tenant's roles, rotates the session id and reloads the UI. Switching tenants is the same call — no re-authentication.
• Cognito simplifies radically: ONE app client (shipped static registration nearly as-is), no pre-token Lambda (Lite plan may suffice), no clientId→tenant map; onboarding shrinks to provision-the-schema + create-the-groups.
• Honest costs stated: one browser session = one active tenant (concurrent multi-tenant tabs — free under subdomains — are impossible here), multi-tenant tokens with no audience binding, tenant-less deep links, and a larger fork surface (S1–S6: session/header resolver, neutral login mapper, switch endpoint, picker UI, header-based M2M tenancy, stale-tab guard). Path-based tenancy (/t/<tenant>/…) is analysed and rejected.
• §8 is a side-by-side trade-off table between the two models; §9 lists the model-specific go-live hypotheses (e.g. authority rebuild on a live session).
• §10 answers horizontal scaling head-on: raising desiredCount today just blocks the second task at boot (ActiveMQ JDBC lock — safe, never split traffic); the layer-by-layer bill for true replicas (external broker, per-node synchronizer replay, boot-race fixes, cache invalidation — shared by both models; plus spring-session + Redis as the only picker-specific item, after which the design survives unchanged); and the picker-specific unit-routing catch (the edge can't see a session-resident tenant → routing cookie + CloudFront Function). Proposal 1's §11 cross-references it.

3. AWS_TENANCY_MODELS_COMPARISON.md — the decision aid

Puts the two models side by side: what is identical in both (groups-only membership, everything below the identity layer, the horizontal-scaling blockers), a 19-row comparison table, explicit pros/cons per model, decision guidance ("subdomains treat tenants as separate products sharing a platform; the picker treats tenants as workspaces inside one product"), the hybrid option (a picker-style dropdown on top of subdomains), and the migration story between the models (the shared t:<tenant>:<role> group convention means switching changes plumbing, never data).

Test plan

• Documentation-only change — no code, no configuration, no CI-relevant files touched
• Markdown renders correctly on GitHub (tables, diagrams, section anchors) in both documents
• Cross-references resolve: file:line anchors spot-checked against current sources (DataSourceInitializer.java:155-159, TenantExtractor.java:44, security-cognito classes, TenantContext.java); the two documents' links to each other work

🤖 Generated with Claude Code