# Admin IA — Audit + Proposed Regrouping **Status:** Phase 1 (proposal + decisions) — captured 2026-05-22 from B3 #10. Open questions resolved in section 7; final IA reflected in section 8. Phase 2 (execution) is mechanical from here. ## Resolved decisions (2026-05-22) User answered the 5 open questions from section 7: 1. **Forms + Document Templates** → moved to **Sales workflow** (not "Content"). Both are workflow inputs, not abstract content. 2. **Webhooks** → keep as its own thing; **new "Integrations" domain** is the right home (Webhooks + Documenso + Website analytics + AI all belong together as "external system + provider config"). 3. **AI configuration** → keep a dedicated `/admin/ai` panel that consolidates every AI feature in one place; lives under the new **Integrations** domain. 4. **`/admin/reports`** → **DELETE entirely** (confirmed duplicative — the dashboard already renders Pipeline funnel + Berth occupancy + KPI cards via widgets). Redirect to `/[portSlug]/dashboard`. 5. **`/admin/settings`** (generic KV editor) → keep visible to all admins under System & observability. **Net effect:** 7 domains instead of 6; 3 pages deleted (ocr, invitations, reports) instead of 2. Final IA in section 8. --- **Goal:** today's 41 admin pages are organically grown and discoverability is poor (test-email lives on Branding, an SMTP test on Email, an OCR-settings duplicate exists on both `/admin/ai` and `/admin/ocr`, etc.). Below: page-by-page inventory + a recommended IA in 6 domains. **Out of scope here:** the actual file moves, route redirects, and nav updates. That's Phase 2 (~4–6h once the IA below is locked). --- ## 1. Page-by-page inventory (current state, 41 pages) Sorted alphabetically. Each row: what the page renders today + its current admin-sections-browser group. | Route | What it renders | Current group | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | | `/admin` | `` — landing tile grid grouped into 5 categories | — | | `/admin/ai` | `` (ai master controls + provider credentials) + `` + AI-suggestions card | Operations | | `/admin/audit` | `` — full mutation log search | Data Quality | | `/admin/backup` | `` — backup posture (read-only) | Operations | | `/admin/berths/bulk-add` | `` — generate berth rows in bulk | (not in landing browser) | | `/admin/berths/reconcile` | `` — review berths missing required fields | (not in landing browser) | | `/admin/branding` | `` (identity) + email branding form + `` + `` | Configuration | | `/admin/brochures` | `` — upload/version port brochures | (not in landing browser) | | `/admin/custom-fields` | `` — per-entity custom-field definitions | Content | | `/admin/documenso` | `` (api creds, signers, templates, behavior) + `` + `` + `` | Configuration ("EOI signing service") | | `/admin/duplicates` | `` — suspected-duplicate clients | Data Quality | | `/admin/email` | `` (from address + smtp) + `` + `` (new) + `` + `` | Configuration | | `/admin/email-templates` | `` — subject-line overrides per transactional template | Content | | `/admin/errors` | error-event list (system errors) | (not in landing browser) | | `/admin/errors/codes` | error-code catalog reference | (not in landing browser) | | `/admin/errors/[requestId]` | single error-event detail | (not in landing browser) | | `/admin/forms` | `` — public inquiry/intake form schemas | Content | | `/admin/import` | CSV import wizard | Data Quality ("Bulk Import") | | `/admin/inquiries` | `` — public-site submissions awaiting triage | Data Quality | | `/admin/invitations` | (empty body — comment says merged into `/admin/users` 2026-05-21) | (not in landing browser) | | `/admin/monitoring` | `` — BullMQ queue health | Operations | | `/admin/monitoring/[queueName]` | `` — single-queue drill-down | (not in landing browser) | | `/admin/ocr` | `` — **DUPLICATES the same form on `/admin/ai`** | (not in landing browser) | | `/admin/onboarding` | `` — cross-page setup checklist for new ports | Operations | | `/admin/pipeline-rules` | per-trigger berth-rules editor + `` | Configuration ("Pipeline auto-advance") | | `/admin/ports` | `` — manage marinas (super-admin only) | Operations | | `/admin/pulse` | `` — pulse chip tuning | Configuration | | `/admin/qualification-criteria` | `` — lead-qualification rubric | Operations | | `/admin/reminders` | `` | Configuration | | `/admin/reports` | `` — saved analytics + ad-hoc queries | Operations | | `/admin/residential-stages` | `` + stage-template registry form | Operations | | `/admin/roles` | `` — role/permission matrix | Access | | `/admin/sends` | `` — brochure + per-berth PDF send retries | Data Quality | | `/admin/settings` | `` — generic system_settings KV editor (escape hatch) | Configuration ("System Settings") | | `/admin/storage` | `` — storage backend selector + migration | Operations | | `/admin/tags` | `` — color-coded tags per entity | Content | | `/admin/templates` | `` — PDF + email document templates (merge-field-driven) | Content | | `/admin/templates/[id]/editor` | per-template editor (PDF + email body) | (not in landing browser) | | `/admin/users` | `` + `` (tabs, merged 2026-05-21) | Access | | `/admin/vocabularies` | `` — admin-editable enum lists | Content | | `/admin/webhooks` | `` + `` + `` | Configuration | | `/admin/website-analytics` | Umami creds form + `` | Operations | --- ## 2. Issues identified ### 2.1 Duplicates 1. **`/admin/ocr` duplicates `/admin/ai`** — same `` is mounted on both. The AI page is the source of truth (it also has the master AI switch + provider creds + AI-suggestions config). **Recommendation: delete `/admin/ocr`** + add a redirect. 2. **`/admin/invitations` is dead** — the page body is empty (per the comment, merged into `/admin/users` 2026-05-21). **Recommendation: delete the route** + add a redirect to `/admin/users?tab=invitations`. ### 2.2 Misplaced cards 1. **`` is on Branding but tests email rendering** — overlap with the new per-template tester on `/admin/email`. **Recommendation: KEEP on Branding** (it's a one-click "does the email LOOK right with current logo/colors?" affordance — that's a branding-validation concern, not a delivery test). Add a sibling link "→ Test individual templates" pointing at `/admin/email`. 2. **`` is on `/admin/email`** — correct home, but it's structurally identical to the noreply SMTP card above it (just a second mailbox). **Recommendation: keep but reformat** so both mailboxes are in matching cards stacked, with a shared "Test send" footer per mailbox. 3. **`` is on `/admin/email`** — actually it's a routing-rule editor (when X event fires, route through Y mailbox). Conceptually closer to a workflow rule than a credentials setting. **Recommendation: keep on Email** for now (the routing IS about email plumbing) but cross-link from Workflows since changing the rule changes behaviour. ### 2.3 Inconsistent naming 1. **"Documenso & EOI"** page title implies EOI lives separately — but EOI generation is one of multiple Documenso flows. **Recommendation: rename to "Signing service (Documenso)"**. 2. **"Bulk Import"** vs `/admin/import` — fine, but the page should explicitly say "Data import" (matches the page title ``). 3. **"Send Log"** vs `/admin/sends` — fine; consider renaming the route slug to `/admin/send-log` for clarity, but that costs cross-references. ### 2.4 Pages not in the admin-sections-browser tile grid A bunch of pages exist as routes but aren't surfaced on `/admin`: - `/admin/berths/bulk-add`, `/admin/berths/reconcile` — only reachable from deep links inside the Berths page - `/admin/brochures` - `/admin/email-templates`, `/admin/tags`, `/admin/vocabularies`, `/admin/custom-fields`, `/admin/forms` — actually these ARE in the browser under "Content", verified - `/admin/qualification-criteria`, `/admin/residential-stages` — under Operations - `/admin/errors`, `/admin/errors/codes`, `/admin/errors/[requestId]` - `/admin/ocr` (duplicate, recommended for deletion) - `/admin/invitations` (dead, recommended for deletion) **Recommendation:** surface every active page on `/admin` (no hidden surfaces — discoverability matters for admins). Move `/admin/berths/bulk-add` + `/admin/berths/reconcile` to a new "Berths admin" landing card. ### 2.5 Categories that don't quite fit - **"Content"** is doing too much heavy lifting — it lumps tag color picker (visual), vocab enum lists (config), form templates (workflow), and document templates (mail merge). These are all things admins _tune_ but their cognitive shape is different. - **"Data Quality"** mixes inbound queues (Inquiry Inbox) with cleanup utilities (Duplicates, Bulk Import) — those serve different daily-workflows. - **"Operations"** is the catch-all for "anything observability or infra-shaped" but also has things that are pure setup (AI configuration, residential pipeline stages). --- ## 3. Proposed IA — 6 domains, 38 pages Two pages deleted (`/admin/ocr`, `/admin/invitations`), one moved out of admin entirely (`/admin/reports` — see below), one new sub-area (`/admin/berths`). Net page count: 41 → 38. ### Domain 1. **Brand & Communication** (5 pages) _Everything about how outbound looks + which channel it ships on._ | Page | Action | Notes | | ------------------------ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `/admin/branding` | KEEP | Logo, colors, app name, email header/footer HTML, the visual "does it look right?" tester. | | `/admin/email` | KEEP | SMTP creds (noreply + sales), routing, per-template tester, SMTP connectivity probe. | | `/admin/email-templates` | KEEP | Subject-line overrides per transactional template. Stays separate from `/admin/email` because the audience is "copywriter" vs "ops". | | `/admin/documenso` | RENAME → "Signing service" | API creds, signer identities, templates, behaviour. Page title currently says "Documenso & EOI" — drop "& EOI" (EOI is one of many doc types). | | `/admin/webhooks` | KEEP | Outbound webhook subscriptions + delivery log. Sits here because webhooks are an outbound-comms channel, same conceptual bucket as email. | ### Domain 2. **Sales workflow** (7 pages) _How the pipeline behaves end-to-end — triggers, scoring, templates._ | Page | Action | Notes | | ------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `/admin/pipeline-rules` | KEEP | Berth-rules engine triggers + auto-advance. | | `/admin/pulse` | KEEP | Deal Pulse chip tuning. | | `/admin/reminders` | KEEP | Default reminder behaviour + digest window. | | `/admin/qualification-criteria` | MOVE FROM "Operations" → here | Lead-qualification rubric — clearly a sales-workflow concern. | | `/admin/residential-stages` | MOVE FROM "Operations" → here | Residential pipeline shape. Same domain as the standard pipeline rules. | | `/admin/forms` | MOVE FROM "Content" → here | Form templates drive lead intake — workflow input, not "content". | | `/admin/templates` | MOVE FROM "Content" → here | Document templates carry merge fields tied to the pipeline (EOI, reservation, contract). These ARE pipeline artefacts. | ### Domain 3. **Catalog** (4 pages) _Tenant-defined data shapes — values that get attached to records._ | Page | Action | Notes | | ---------------------- | -------------------------- | ---------------------------------------------------------------------------- | | `/admin/vocabularies` | KEEP | Admin-editable enum lists (berth_side_pontoon_options, lead_category, etc.). | | `/admin/tags` | KEEP | Color tags. | | `/admin/custom-fields` | KEEP | Per-entity field definitions. | | `/admin/brochures` | MOVE FROM ungrouped → here | Brochure assets are catalog artefacts (per-port versioned PDFs). | ### Domain 4. **Identity & access** (3 pages) _Who can use the system and what they can do._ | Page | Action | Notes | | -------------- | ------ | -------------------------------------------- | | `/admin/users` | KEEP | Active users + invitations (already merged). | | `/admin/roles` | KEEP | Role/permission matrix. | | `/admin/ports` | KEEP | Super-admin only; per-port management. | ### Domain 5. **Inbox & data quality** (6 pages) _Stuff that lands in admin queues + tools to clean up data._ | Page | Action | Notes | | ------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- | | `/admin/inquiries` | KEEP | Public-site form submissions. | | `/admin/sends` | KEEP | Brochure + per-berth-PDF send retries. | | `/admin/duplicates` | KEEP | Suspected-duplicate review queue. | | `/admin/import` | KEEP | CSV imports. | | `/admin/berths` | NEW INDEX | Landing page that surfaces the two berth-admin tools below. | | `/admin/berths/bulk-add` | MOVE FROM ungrouped → keep route, surface via /admin/berths | Bulk berth row generator. | | `/admin/berths/reconcile` | MOVE FROM ungrouped → keep route, surface via /admin/berths | Berth-pdf reconciliation queue. | (Counted as one Berths entry on the landing tile + the two existing routes as sub-pages.) ### Domain 6. **System & observability** (10 pages) _Infra, observability, escape hatches._ | Page | Action | Notes | | ------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | | `/admin/audit` | KEEP | Mutation audit log. | | `/admin/monitoring` | KEEP | BullMQ queue health. | | `/admin/monitoring/[queueName]` | KEEP | Single-queue detail. | | `/admin/errors` | SURFACE on landing | Error-event list (currently hidden from `/admin` tile grid). | | `/admin/errors/codes` | KEEP as sub-page | Linked from `/admin/errors`. | | `/admin/errors/[requestId]` | KEEP as sub-page | Linked from `/admin/errors`. | | `/admin/backup` | KEEP | Backup posture. | | `/admin/storage` | KEEP | Storage backend selector + migration. | | `/admin/website-analytics` | KEEP | Umami creds. | | `/admin/ai` | KEEP | AI config (master switch, providers, OCR settings, suggestions). | | `/admin/settings` | KEEP | Generic KV editor (escape hatch for advanced flags). Stays in this domain because it's an admin-debug surface, not a normal-day setting. | | `/admin/onboarding` | KEEP, FLOATS | Cross-cutting setup checklist. Stays accessible from `/admin` landing but doesn't belong in any single domain — it links to many. | ### Out of admin entirely | Page | Action | Rationale | | ---------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/admin/reports` | MOVE OUT → `/[portSlug]/reports` | Reports are an end-user feature, not admin config. Today it lives in admin only because it's permission-gated; should be a top-level nav item with the same permission gate. Defer to a follow-up; for the IA pass, just stop surfacing it on `/admin`. | ### Deleted | Page | Action | Rationale | | -------------------- | ----------------------------- | -------------------------------------------- | | `/admin/ocr` | DELETE + 301 → `/admin/ai` | Duplicate of `/admin/ai`. | | `/admin/invitations` | DELETE + 301 → `/admin/users` | Empty page; functionality merged 2026-05-21. | --- ## 4. Misplaced cards / sub-section moves These are smaller-grained moves _within_ the new IA — cards that should change page even though the routes stay put. 1. **`` (currently on `/admin/branding`)** → KEEP on Branding (visual brand check); add a "→ Test individual templates" link pointing at `/admin/email#test-template`. 2. **`` (currently on `/admin/email`)** → KEEP on Email; cross-link from a "Routing rules" subsection of the new Workflow domain. 3. **`` (currently on `/admin/documenso`)** → KEEP; consider surfacing duplicate on `/admin/templates` (since "Sync from Documenso" populates template IDs there). 4. **``** → consider exposing a slim version as a banner on `/admin` landing for ports that haven't completed setup. --- ## 5. Proposed `/admin` landing tile groups The `admin-sections-browser.tsx` array should be rebuilt to match the 6 domains above. Sketch: ```ts const SECTIONS: AdminSection[] = [ { title: 'Brand & Communication', description: 'How outbound looks and which channels it ships on.', items: ['branding', 'email', 'email-templates', 'documenso', 'webhooks'], }, { title: 'Sales workflow', description: 'Pipeline behaviour, scoring, document + form templates.', items: [ 'pipeline-rules', 'pulse', 'reminders', 'qualification-criteria', 'residential-stages', 'forms', 'templates', ], }, { title: 'Catalog', description: 'Tenant-defined enums, tags, custom fields, and brochures.', items: ['vocabularies', 'tags', 'custom-fields', 'brochures'], }, { title: 'Identity & access', description: 'Who can use the system and what they can do.', items: ['users', 'roles', 'ports'], }, { title: 'Inbox & data quality', description: 'Admin queues + cleanup tools.', items: ['inquiries', 'sends', 'duplicates', 'import', 'berths'], }, { title: 'System & observability', description: 'Infra, observability, escape hatches.', items: [ 'audit', 'monitoring', 'errors', 'backup', 'storage', 'website-analytics', 'ai', 'settings', ], }, ]; ``` Onboarding checklist surfaces above the grid (or as a banner on incomplete ports), not as a tile. --- ## 6. Phase 2 execution plan (~4–6h) Once the above IA is approved (or amended), the migration is mechanical: 1. **Update `admin-sections-browser.tsx`** to the 6-domain shape above. (~30 min) 2. **Delete `/admin/ocr`** + add `redirect()` to `/admin/ai`. (~10 min) 3. **Delete `/admin/invitations`** + add `redirect()` to `/admin/users`. (~10 min) 4. **Rename "Documenso & EOI"** → "Signing service" (page title + landing label). (~5 min) 5. **Create `/admin/berths/page.tsx`** index that surfaces bulk-add + reconcile. (~30 min) 6. **Move `/admin/reports` out of admin** — touches sidebar nav + landing browser + permission docs. Defer to its own task if scope creeps. (~1h) 7. **Cross-link cards** per section 4 (EmailPreviewCard → /admin/email link, etc.). (~30 min) 8. **Smoke pass** — click every tile, confirm every page loads, every redirect lands. (~30 min) 9. **Audit doc update** — mark B3 #10 SHIPPED in `alpha-uat-master.md`. (~10 min) Total: ~4 h plus ~1 h for the Reports move if we include it. --- ## 7. Open questions (resolved) | # | Question | Decision | | --- | ---------------------------------------- | ------------------------------------------------------------------------------- | | 1 | Forms + Document Templates placement | Moved to **Sales workflow** (not Content) | | 2 | Webhooks placement | **New "Integrations" domain** (webhooks + documenso + website-analytics + ai) | | 3 | AI configuration placement | Keep dedicated `/admin/ai` panel; lives under **Integrations** | | 4 | `/admin/reports` | **DELETE entirely** (duplicates dashboard); redirect to `/[portSlug]/dashboard` | | 5 | `/admin/settings` (KV editor) visibility | Keep visible to all admins under **System & observability** | --- ## 8. Final IA — 7 domains, 38 pages After resolutions. Three pages deleted (`/admin/ocr`, `/admin/invitations`, `/admin/reports`); one new sub-area (`/admin/berths` index); one new domain (Integrations) split out from Brand & Communication. ### Domain 1. **Brand & Communication** (3 pages) _How outbound LOOKS — visual and copy._ - `/admin/branding` — logo, colors, app name, email shell HTML, EmailPreviewCard (visual check) - `/admin/email` — SMTP creds (noreply + sales), routing, per-template tester, SMTP probe - `/admin/email-templates` — subject-line + copy overrides per transactional template ### Domain 2. **Sales workflow** (7 pages) _How the pipeline BEHAVES — triggers, scoring, templates._ - `/admin/pipeline-rules` — berth-rules engine + auto-advance - `/admin/pulse` — Deal Pulse chip tuning - `/admin/reminders` — default behaviour + digest - `/admin/qualification-criteria` — lead-scoring rubric - `/admin/residential-stages` — residential pipeline shape - `/admin/forms` — lead intake form templates (moved from Content) - `/admin/templates` — document templates with merge fields (moved from Content) ### Domain 3. **Catalog** (4 pages) _Tenant-defined data shapes that attach to records._ - `/admin/vocabularies` — admin-editable enum lists - `/admin/tags` — color tags - `/admin/custom-fields` — per-entity field definitions - `/admin/brochures` — per-port versioned PDF assets ### Domain 4. **Identity & access** (3 pages) - `/admin/users` — active users + invitations (merged) - `/admin/roles` — role/permission matrix - `/admin/ports` — super-admin only, per-port management ### Domain 5. **Inbox & data quality** (5 pages, 1 sub-index) _Admin queues + cleanup tools._ - `/admin/inquiries` — public-site submissions - `/admin/sends` — outbound send retry log - `/admin/duplicates` — duplicate-client review queue - `/admin/import` — CSV imports - `/admin/berths` — **NEW** index page surfacing the two existing sub-tools: - `/admin/berths/bulk-add` (bulk row generator) - `/admin/berths/reconcile` (berth-pdf reconciliation queue) ### Domain 6. **Integrations** (4 pages) — NEW DOMAIN _External-system + provider configuration._ - `/admin/documenso` — signing service (rename from "Documenso & EOI" → "Signing service") - `/admin/webhooks` — outbound subscriptions + delivery log - `/admin/website-analytics` — Umami creds - `/admin/ai` — dedicated AI panel consolidating master switch + provider creds + OCR settings + AI-suggestions config ### Domain 7. **System & observability** (7 pages + 1 floating) _Infra, observability, escape hatches._ - `/admin/audit` — mutation audit log - `/admin/monitoring` — BullMQ queue health (+ `/admin/monitoring/[queueName]` sub-page) - `/admin/errors` — error-event list (+ `/admin/errors/codes` + `/admin/errors/[requestId]`) - `/admin/backup` — backup posture - `/admin/storage` — storage backend selector + migration - `/admin/settings` — generic KV editor (escape hatch) - `/admin/onboarding` — cross-cutting setup checklist (floats above the grid for incomplete ports) ### Deleted | Page | Action | Rationale | | -------------------- | -------------------------------------- | ---------------------------------------------------- | | `/admin/ocr` | DELETE + 301 → `/admin/ai` | Duplicate of `/admin/ai`'s OcrSettingsForm | | `/admin/invitations` | DELETE + 301 → `/admin/users` | Empty page; merged into `/admin/users` on 2026-05-21 | | `/admin/reports` | DELETE + 301 → `/[portSlug]/dashboard` | Three widgets all already on the dashboard | --- ## 9. Phase 2 execution plan (~4-5 h) Updated to reflect the resolved decisions. Reports move-out becomes a delete (simpler). 1. **Update `admin-sections-browser.tsx`** to the 7-domain shape above. (~45 min — 7 groups, ~30 tiles) 2. **Delete `/admin/ocr`** + add `redirect()` to `/admin/ai`. (~10 min) 3. **Delete `/admin/invitations`** + add `redirect()` to `/admin/users`. (~10 min) 4. **Delete `/admin/reports`** + add `redirect()` to `/[portSlug]/dashboard`. (~10 min) + remove from sidebar nav + landing browser. (~15 min) 5. **Rename `/admin/documenso`** page title → "Signing service" (page title + landing tile label). (~5 min) 6. **Create `/admin/berths/page.tsx`** index page surfacing bulk-add + reconcile sub-tools. (~30 min) 7. **Cross-link ``** on Branding to add a "→ Test individual templates" link pointing at `/admin/email#test-template`. (~10 min) 8. **Smoke pass** — click every tile on the new `/admin` landing, confirm every page loads, every redirect lands. (~30 min) 9. **Update `alpha-uat-master.md`** Bucket 3 #10 → SHIPPED with this proposal's commit hash. (~5 min) Total: ~3.5-4 h.