Docs / 00-shared / INFORMATION-ARCHITECTURE.md

#Information Architecture

One navigation model, expressed natively on each platform. Section names, order, grouping and icon meanings are identical everywhere.

#1. Navigation tree (screen IDs and routes)

Substratal Hub
├── PERSONAL
│   ├── Home                 /                       APP-01  (APP-02 /apps/:appId, APP-05 /apps/past)
│   ├── Inbox  (unread n)    /inbox                  NTF-01  (NTF-02 /inbox/:notificationId)
│   ├── Organizations        /orgs                   ORG-01  (ORG-03 /orgs/:orgId/members, ORG-06 …/apps, BIL-02 …/subscription, ORG-08 …/settings)
│   ├── Account              /account                ACC-01  (ACC-04 /account/security, NTF-03 /account/devices, ACC-07 /account/privacy)
│   ├── Plan & Billing       /billing                BIL-01  (BIL-03 /billing/return)
│   └── Settings             /settings               SET-01  (SET-02 /settings/apps/:appId)
├── ADMINISTRATION           /admin   (GLB-02 Manage hub on compact layouts)
│   ├── Users                /admin/users            USR-01  (USR-03 /admin/users/:userId + tabs Access ACX-01, Roles ROL-04, Sessions USR-04, Notifications NTF-05, Activity)
│   ├── Access               /admin/access           ACX-05
│   ├── Roles                /admin/roles            ROL-01  (ROL-02 /admin/roles/:roleId)
│   ├── Audit Log            /admin/audit            AUD-01  (AUD-02 /admin/audit/:eventId)
│   └── Send notification    /admin/notifications/new NTF-06
└── DEVELOPER                /dev     (GLB-02 Manage hub on compact layouts)
    ├── Applications         /dev/apps               APL-01  (APL-03 /dev/apps/:appId + tabs incl. Push APL-07)
    ├── API Keys             /dev/keys               KEY-01  (KEY-04 /dev/keys/:keyId)
    ├── Webhooks             /dev/webhooks           WHK-01  (WHK-03 /dev/webhooks/:hookId)
    └── Tenant               /dev/tenant             BIL-04

Outside the shell:  /sign-in  /sign-in/mfa  /sign-up  /verify-email  /forgot-password  /reset-password  /invite
Overlays:           Command palette GLB-01 · Turn on notifications NTF-04 · System states GLB-03

#2. Visibility rules (from Capabilities)

Hide what the person can never use. Show but disable with a reason what they can see but not do right now ("Managed by Substratal — you can only turn it off", "You're the last admin", "Seed roles can't be edited").

#3. Navigation container per platform

Rule: wide = every section in a sidebar; compact = 5 destinations with Administration and Developer combined in the Manage hub (GLB-02), which is removed when the person has no rights in either. The Inbox destination carries the unread badge on every layout.

#4. Routes and deep links

The route column in SCREEN-SPECS.md is canonical. Web host: https://dashboard.substratalapps.com (the host the API spec uses in its billing examples).

Routes encode the view's state (tab, filters as query). Emailed links (/verify-email?token=, /reset-password?token=, /invite?token=, /orgs/:orgId/invitation) and Stripe returns (/billing/return?checkout=…, /orgs/:orgId/subscription?checkout=…) open the installed app when present, else the web app. A notification's action_url that is a Hub route opens in-app; any other URL opens externally. Restoring a route without permission shows the Forbidden state, not a redirect.

#5. Section icons (meaning → platform symbol)

#6. Standard screen anatomy