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).

4. AWS_COGNITO_TENANT_ROLES_LIMITS.md — the storage-limits analysis

Standalone; changes none of the three documents above (its §9 records what it would imply for them). Prompted by the real scale — a user in 20–30 tenants, each tenant defining ~10 roles — it shows that the prefixed-group model the other documents specify does not survive those numbers: "Groups to which each user can belong: 100 — not adjustable" allows at most ~3 held roles per tenant at 30 tenants, and the stated worst case needs 300. Covers the defined-vs-held distinction (pool quota 10,000 vs per-user 100), every applicable quota with its adjustability, the arithmetic (group grid, ~9 KB claims carried in both tokens, the non-adjustable 25 RPS account-wide write quota, reverse queries, propagation delay), six options with the wall each hits, and the recommendation: Cognito for identity, an external store for the tenant ↔ user ↔ roles graph.

5. AWS_TENANT_PICKER_HORIZONTAL_SCALING.md — the session layer, in depth

Expands §10 of the picker proposal into a dedicated design note with diagrams. The claim in two halves: externalising the HTTP session makes the picker design horizontally scalable (it removes the only picker-specific blocker, and the design survives unchanged — only where the session lives moves), and on its own it does not make the platform scalable, because five further blockers are platform-level and identical for the subdomain model. Worth adopting at one instance regardless: sessions then survive deploys.

Three repository-verified facts shape the recommendation: HttpSessionFacade.setAttribute(String, String) means user code can only put Strings in the session, so the serialization surface reduces to one principal class rather than an audit of every project; the same class dirties the session on every access, producing a store write per request — the codebase-specific reason to prefer Redis over spring-session-jdbc (which is still presented fairly as the no-new-infrastructure option); and spring.session.timeout=8h is already in application.properties, inert today, live the moment the dependency lands. Also covers the tenant-switch propagation window, the indexed repository making "eject a user immediately" implementable, the SESSION-vs-JSESSIONID cookie rename, ElastiCache topology, a three-phase rollout, and the maxmemory-policy setting that fails silently. Two items are flagged for experiment rather than asserted — notably whether JSON session serialization is viable under Spring Boot 4.1.0's Jackson 3 web layer.

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