# IAM UX Information Architecture v1 (Review Draft)

Purpose:
- Define the UI model for tenant/platform IAM now that backend APIs are largely in place.
- Make implementation sequencing explicit so UI work can proceed without backend ambiguity.

Inputs:
- `doc/api/openapi.draft.yaml`
- `doc/architecture/Role_and_Policy_Lifecycle_Model.md`
- `doc/architecture/User_Onboarding_Model.md`
- `doc/architecture/Service_Account_Model.md`

## 1. Scope and Principles

Scope in this draft:
1. Navigation and screen model for IAM capabilities already present in API.
2. Role-based visibility rules for platform admin vs tenant admin vs project user.
3. API-to-screen contract mapping and identified UI gaps.

Principles:
1. Separate **Platform IAM** from **Tenant IAM** to prevent role-check confusion.
2. Keep project lifecycle, tenant/project membership, and service account
   controls under one coherent Access/IAM section.
3. Do not expose API features without clear ownership and guardrails in UI.

## 2. IAM Navigation Model

### 2.1 Top-level IA
- `Access`
  - `Projects`
  - `Team & Memberships`
  - `Service Accounts`
  - `Platform Roles` (platform admin only)
  - `App Entitlements` (project scope)

### 2.2 Existing route placement
- Keep current `/settings/team` as tenant-facing entry until full IA cutover.
- Keep `/admin/users/:user_id` membership controls until platform IAM pages are added.

## 3. Role-Based Visibility Matrix (UI)

| Surface | platform_superadmin | platform_ops | tenant_owner | tenant_admin | project_owner/admin | project_member/viewer |
|---|---|---|---|---|---|---|
| Team & Memberships (tenant scope) | yes | yes (read-heavy) | yes | yes | no | no |
| Service Accounts (project scope) | yes | yes | yes | yes | yes | no |
| Platform Roles | yes | no | no | no | no | no |
| App Entitlements (project scope) | yes | yes | yes | yes | yes | read/no-write |

Notes:
1. Platform users can enter tenant/project context but actions remain policy-gated.
2. Service accounts never receive platform role controls in UI.
3. Role strings shown in API and policy evaluation are canonical; UI-friendly labels are presentation-only and must not change API enum values.

## 4. Screen Flows and API Contracts

## 4.1 Projects

Flow:
1. List projects visible in the current tenant/workspace.
2. Create a new project.
3. Rename/update project metadata.
4. Set a project as the default current context.
5. Delete a project through a guarded destructive flow.

API mapping:
- `GET /api/v1/projects`
- `POST /api/v1/projects`
- `PATCH /api/v1/projects/{project_id}`
- `DELETE /api/v1/projects/{project_id}`
- `POST /api/v1/projects/{project_id}/set-default`

UX rules:
- Project switching belongs in the global context bar, but project lifecycle
  management belongs in a routed page.
- The project page should show enough context for users to understand what the
  project contains and which downstream surfaces depend on it.
- Delete must be policy-aware and explain why it is blocked when the backend
  refuses the action.

## 4.2 Team & Memberships

### Tenant-admin flow
1. List tenant users.
2. Create tenant user (username/password in MVP).
3. Bind/update tenant/project role assignments.

API mapping:
- `GET /api/v1/tenant/users`
- `POST /api/v1/tenant/users`
- `POST /api/v1/tenant/users/{user_id}/memberships`

### Platform-admin flow
1. Create global user.
2. Select tenant.
3. Select tenant project.
4. Bind membership with tenant/project roles.

API mapping:
- `POST /api/v1/admin/users`
- `GET /api/v1/admin/tenants`
- `GET /api/v1/admin/tenants/{tenant_id}/projects`
- `POST /api/v1/admin/tenants/{tenant_id}/memberships`

## 4.3 Platform Roles

Flow:
1. Inspect a user’s active platform roles.
2. Bind one platform role.
3. Revoke one platform role.

API mapping:
- `GET /api/v1/admin/users/{user_id}/platform-roles`
- `POST /api/v1/admin/users/{user_id}/platform-roles`
- `DELETE /api/v1/admin/users/{user_id}/platform-roles/{role}`

## 4.4 Service Accounts

Flow:
1. List service accounts for active project.
2. Create service account with allowlist + TTL profile.
3. Rotate credential.
4. Disable service account.
5. View detail and last-used metadata.

API mapping:
- `GET /api/v1/projects/{project_id}/service-accounts`
- `POST /api/v1/projects/{project_id}/service-accounts`
- `POST /api/v1/projects/{project_id}/service-accounts/{service_account_id}/rotate-key`
- `POST /api/v1/projects/{project_id}/service-accounts/{service_account_id}/disable`
- `GET /api/v1/projects/{project_id}/service-accounts/{service_account_id}`

## 4.5 App Entitlements (IAM-adjacent policy surface)

Flow:
1. List app catalog + versions.
2. View per-project entitlement status.
3. Enable/disable entitlement and update policy overrides.

API mapping:
- `GET /api/v1/apps/catalog`
- `GET /api/v1/apps/catalog/{app_slug}/versions`
- `GET /api/v1/projects/{project_id}/apps/entitlements`
- `PUT /api/v1/projects/{project_id}/apps/entitlements/{app_slug}`

Platform admin catalog lifecycle (separate admin console path):
- `POST /api/v1/admin/apps/catalog/{app_slug}/versions/{version}/publish`
- `POST /api/v1/admin/apps/catalog/{app_slug}/versions/{version}/deprecate`

## 5. Current UI Gap Audit (API exists, UI missing)

Not yet surfaced in routed pages:
1. Project lifecycle pages.
2. Platform role management page (list/bind/revoke).
3. Dedicated service accounts pages.
4. Dedicated app entitlements pages.
5. Admin app catalog publish/deprecate controls.

Partially surfaced:
1. Tenant and platform membership binding is embedded in existing user/team pages, not in unified IAM IA.

## 6. Recommended Delivery Sequence

1. **Access/IAM foundation shell**
- Add `Access` nav group and route containers.
- Keep existing pages functional; add links to current equivalents where needed.

2. **Projects first**
- Project lifecycle is already contract-backed and should not remain hidden
  behind the global project selector.

3. **Service Accounts first**
- High leverage for app/operator integrations.
- Minimal dependency on unresolved onboarding UX.

4. **Platform Roles page**
- Closes platform admin operational gap.
- Enforces clear platform/tenant separation in UI.

5. **App Entitlements page**
- Enables controlled app rollout per project.

6. **Consolidate Team & Memberships**
- Move existing `/settings/team` and admin membership fragments into IAM IA.

## 7. Error and Traceability Requirements (IAM Screens)

Every IAM mutation screen must:
1. Render canonical `ErrorResponse` (`code`, `message`, `correlation_id`).
2. Keep `correlation_id` copy action in error state.
3. Include `Idempotency-Key` on mutation calls.
4. Log UI-side context: `project_id`, `tenant_id`, action name.

## 8. Out of Scope (for this draft)

1. Custom role authoring UI.
2. Group lifecycle UX.
3. Tenant federation IdP admin UI (OIDC/SAML provider management).
4. OPA policy authoring UI.