> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-31: ADR-31

> # Title 4-level routing hierarchy: Tenant → Org → Project → Agent  # Decision Adopt a four-level routing hierarchy with all levels distinct: Enterprise/Tenant (

<Info>**Status:** `accepted` · **ADR-31** · Filed 2026-04-30</Info>

# Title

4-level routing hierarchy: Tenant → Org → Project → Agent

# Decision

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 with `feedback_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

1. **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.
2. **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.
3. **Flat — Tenant only, project\_id is just a tag on signals.** Rejected outright; violates project isolation as a hard guarantee.

# Status

accepted

# References

* SPEC-056 §Architecture
* Memory: `feedback_routing_granularity`, `feedback_same_code_everywhere`