# TENANT_ADMIN_WALKTHROUGH — Oshun Tenant Admin (institution cockpit)

A granular, checklist-driven inventory of every view and interaction in the
Oshun **tenant-admin** app — the institution/tenant cockpit served from
`apps/oshun/tenant-admin`. Parallel to the V1 PWA walkthrough at
[`../WALKTHROUGH/`](../WALKTHROUGH/README.md) and the operator cockpit at
[`../ADMIN_WALKTHROUGH/`](../ADMIN_WALKTHROUGH/README.md); same per-view file
format, different app.

## What this is (and is not)

- **Is**: A per-view checklist for every page in the tenant-admin app — what a
  tenant administrator (school district, institution) clicks, reads, and (once
  the surfaces are wired) edits.
- **Is not**: A duplicate of `WALKTHROUGH/` or `ADMIN_WALKTHROUGH/`. The
  tenant-admin app is a separate Next.js application with its own `TenantShell`,
  middleware, session cookie (`oshun-tenant-session`), and IA. Findings don't
  carry one-to-one across apps.

## Surface map

15 routes, single Next.js app at `apps/oshun/tenant-admin`. No PWA manifest, no
service worker. Auth: `getTenantServerSession()` →
`canEnterTenantShell(scopes, tenantId)` requires `tenant:admin:*` or
`tenant:admin:{tenantId}`; `middleware.ts` redirects all non-public paths to
`/unauthorized`. Public paths: `/handoff`, `/unauthorized`.

| Group               | Routes | Pages                                 |
| ------------------- | ------ | ------------------------------------- |
| **identity-access** | 3      | `identity`, `members`, `roles`        |
| **governance**      | 4      | `audit`, `content`, `data`, `policy`  |
| **operations**      | 3      | `agents`, `notifications`, `status`   |
| **integrations**    | 1      | `integrations`                        |
| **configuration**   | 1      | `help`                                |
| **meta**            | 3      | `/` (home), `handoff`, `unauthorized` |

Group taxonomy derives from the tenant workspace definitions in
`libs/oshun/navigation/src/tenant-ia.ts`.

## Folder layout

```
TENANT_ADMIN_WALKTHROUGH/
  README.md                # this file
  home.md  agents.md  audit.md  content.md  data.md  handoff.md  help.md
  identity.md  integrations.md  members.md  notifications.md  policy.md
  roles.md  status.md  unauthorized.md
  matrix/
    routes.csv             # route,group,source,target,status,notes
    coverage.md            # narrative + cross-cutting findings
```

## How to read a per-view file

Each file follows the template in
[`../WALKTHROUGH/00-conventions.md`](../WALKTHROUGH/00-conventions.md):
frontmatter (path, surface, domain, auth, source, status, last_walked), then
Purpose, Entry points, Layout regions, States, Interactions, Data & contracts,
Cross-references, Open questions. Every `- [ ]` is a verifiable check. Status:
stub / drafted / walked / stale (tracked in `matrix/routes.csv`).

## Status

All 15 routes are documented: **14 drafted** from code reading and the Identity
workspace **walked** against live tenant-scoped SSO data. The next pass is to
walk the remaining 14 views against a running tenant-admin build. See
[`matrix/coverage.md`](./matrix/coverage.md) for the cross-cutting findings,
including the three BFF-backed workspaces and the remaining read-only
projections.