Status:
accepted · ADR-31 · Filed 2026-04-30Title
4-level routing hierarchy: Tenant → Org → Project → AgentDecision
Adopt a four-level routing hierarchy with all levels distinct: Enterprise/Tenant (top, billing/contract entity), Org (departmental sub-grouping inside a tenant), Project (working scope), Agent (active worker / persona). Each level is independently addressable in the routing layer and has its own Redis pubsub channel. Personal Install defaults: tenant=“Personal”, org=“Personal” (auto-created at install time, no operator prompt for personal mode).Rationale
Mature multi-tenant SaaS converges on this shape (AWS Org → OU → Account → Resource; GitHub Enterprise → Organization → Repo → User; Atlassian Organization → Site → Project → Issue). Treating Tenant and Org as the same level is acceptable for single-org enterprises today but forces a re-plumbing of every channel name, header, and authorization gate the moment a multi-department customer arrives. Frank’s posture — “all the information is there so don’t be lazy” — pushes the schema and routing layer to carry the full hierarchy from day one even when only one Org exists. This pairs withfeedback_routing_granularity and feedback_same_code_everywhere: same code path runs for personal-1-org and commercial-N-orgs, only the data populating it differs.
Alternatives Considered
- 3 levels: Tenant/Org → Project → Agent. Smaller migration, but conflates the legal entity (who pays) with the logical sub-grouping (which department). Forces re-plumb on first multi-org customer.
- 5 levels: Tenant → Org → Team → Project → Agent. Considered; rejected as overkill for the foreseeable future. Teams can be a flat tag/label on agents within a project; introducing a Team layer adds a routing channel that has no observed consumer.
- Flat — Tenant only, project_id is just a tag on signals. Rejected outright; violates project isolation as a hard guarantee.
Status
acceptedReferences
- SPEC-056 §Architecture
- Memory:
feedback_routing_granularity,feedback_same_code_everywhere