ADR-026: Multi-Org Architecture Overview¶
Audience: common — see ADR index.
Status: Accepted Date: 2026-08-19 Deciders: Portal team Scope: End-to-end multi-org architecture — ties together ADRs 020–024 and 027
Context¶
The multi-org initiative delivers multi-AAP-organization support for the Ansible Automation Portal. The feature spans namespace isolation, catalog entity naming, template taxonomy, auth/session management, and sync UX. ADRs 020–024 and 027 capture those decisions; this document provides the architectural overview that connects them. ADR-027 is Accepted and is the governing contract for catalog names and namespaces; it partially supersedes ADR-020. Shared frontend library extraction (ADR-025 / plugin factory) is separate future work — not part of multi-org.
Architecture¶
flowchart TB
subgraph AAP["AAP Controller"]
GW["Gateway API"]
ORG1["Org: Engineering"]
ORG2["Org: Operations"]
ORG3["Org: Security"]
GW --> ORG1 & ORG2 & ORG3
ORG1 --> JT1["Job Templates"]
ORG1 --> T1["Teams / Users"]
ORG2 --> JT2["Job Templates"]
ORG2 --> T2["Teams / Users"]
ORG3 --> JT3["Job Templates"]
ORG3 --> T3["Teams / Users"]
end
subgraph CONFIG["Portal Configuration"]
FFmultiOrgEnabled: true
ORGS["orgs:\n- Engineering\n- Operations"]
end
subgraph SYNC["Catalog Sync ‹ADR-020, ADR-027, ADR-024›"]
direction LR
AEP["AapEntityProvider\n‹orgs, teams, users›"]
JTP["AAPJobTemplateProvider\n‹job templates›"]
SIG["Backstage Signals\n‹real-time sync state›"]
AEP ~~~ JTP ~~~ SIG
end
subgraph CATALOG["Backstage Catalog ‹flag on; ADR-027 identity›"]
subgraph NS1["namespace: aap-{orgId}"]
G1["Groups\naap-org-*\naap-team-*"]
E1["Templates\naap-jt-*\nautomation-template"]
end
subgraph NS2["namespace: aap-{orgId}"]
G2["Groups\naap-org-*\naap-team-*"]
E2["Templates\naap-jt-*\nautomation-template"]
end
subgraph DEF["namespace: default"]
USERS["Users\n‹flag off: raw; flag on: aap-user-{id}›"]
SCM["Templates\nsource: scm"]
end
end
subgraph AUTH["Auth and RBAC ‹ADR-022›"]
OAUTH["AAP OAuth + PKCE"]
TOKEN["User Token\n‹org membership›"]
LOGOUT["Logout Sync\n‹AAP to Portal›"]
end
subgraph UI["Self-Service UI"]
HEADER["PageHeaderSection\n‹Sync Now + Last Synced›"]
FILTERS["Filters:\nCategories | Tags\nSource Type | Owner"]
CARDS["Template Cards\n‹filtered by source›"]
end
CONFIG -->|"feature flag gates"| SYNC
AAP -->|"API sync"| SYNC
SYNC -->|"namespace-isolated\nentities"| CATALOG
SYNC -->|"sync status"| SIG
SIG -->|"real-time\nupdates"| HEADER
AUTH -->|"token-based\nvisibility"| CATALOG
OAUTH --> TOKEN
TOKEN -->|"org membership\ndrives access"| UI
CATALOG --> FILTERS
FILTERS --> CARDS
Data Flow¶
-
Configuration — Admin enables
multiOrgEnabled: trueand lists target orgs. Feature flag gates multi-org names and namespaces (ADR-020, ADR-027). With the flag off, org-scoped entities keep slug names indefault. -
Sync —
AapEntityProvidersyncs orgs, teams, users;AAPJobTemplateProvidersyncs job templates. Under ADR-027, the flag-on entitymetadata.nameuses{source}-{type}-{id}(e.g.aap-org-1,aap-team-12,aap-jt-5238,aap-user-42) and each org's entities land in{source}-{org-id}(e.g.aap-2,aap-3); users stay indefaultasaap-user-{id}. With the flag off, names and namespaces stay as today (including raw usernames). Backstage Signals push real-time sync state to the UI (ADR-024). -
Namespace Isolation — Under ADR-027 with
multiOrgEnabled: true, groups and templates are scoped per{source}-{org-id}namespace. Two orgs with a team named "Engineering" coexist as e.g.group:aap-2/aap-team-5andgroup:aap-3/aap-team-9; group display names include org context (Team: Engineering ({org})). Users remain indefaultto avoid duplication across orgs (ADR-020, ADR-027). -
Template Taxonomy — Synced templates use
spec.type: automation-templatewithansible.com/template-source: aap-template. User-added SCM templates usesource: scm. The Source Type filter enables UI-level categorization (ADR-021). -
Auth and Session — Users authenticate via AAP OAuth (PKCE). With the flag off, catalog and auth resolve the raw AAP username. Under ADR-027, the flag-on contract uses
{source}-user-{id}and auth looks up / creates by AAP user id. Logout from AAP terminates the portal session (ADR-022). -
UI —
PageHeaderSectionprovides Sync Now with progress popover and last-synced tooltip. Source Type, Categories, Tags, and Owner filters narrow the template view.
ADR Index¶
| ADR | Title | Scope |
|---|---|---|
| ADR-020 | Namespace Isolation | Feature flag, users / aap-admins in default, config-time collision validation; names/namespaces superseded by ADR-027 |
| ADR-021 | Template Type Taxonomy | automation-template type, template-source annotation |
| ADR-022 | RBAC and Auth | AAP as RBAC source of truth, OAuth, logout sync |
| ADR-023 | Per-Template RBAC Filtering | Execute visibility filtering (future — separate epic) |
| ADR-024 | Sync UX — Backstage Signals | Real-time sync state, progress popover |
| ADR-027 | Catalog Entity Naming and Namespaces | Accepted: flag off → slug / raw user in default; flag on → {source}-{type}-{id} + {source}-{org-id} + {source}-user-{id} |
Consequences¶
What this enables¶
- Single portal instance serves multiple AAP orgs without entity collisions (id-based names +
{source}-{org-id}namespaces when flag on, per ADR-027) - Flag-off upgrades keep slug entity names in
default(no ref break for single-org) - Source-based template filtering across AAP, SCM, and future sources
- Consistent sync UX across Templates, Collections, and Git Repos pages
What remains out of scope¶
- Per-template execute RBAC visibility (ADR-023 — separate epic)
- Per-org granular sync selection in the UI
- Workflow and orchestrator template sources (documented, not implemented)
- Shared frontend library /
portal-react(ADR-025 — plugin factory; not multi-org)
Related¶
- ADR-020 — Multi-org namespace isolation (partially superseded by ADR-027)
- ADR-021 — Template type taxonomy
- ADR-022 — Multi-org RBAC and auth
- ADR-023 — Per-template RBAC visibility filtering
- ADR-024 — Sync UX: Backstage signals and unified pattern
- ADR-027 — Catalog entity naming and namespaces (governing contract)