Admin Panel Refactor: Organization-Grouped Tenant Management

Date: 2026-04-24 Sub-project: 2 of 2 in the organization/tenant refactor. Depends on: Sub-project 1 (rename + scope cleanup) must be merged first. Status: Design — awaiting review.

Context

Today the admin's /tenants page renders two flat tables side-by-side (organizations and tenants, under their post-rename names) plus a prompt-customizations matrix. Tenant-level configuration (integrations, notifications, master data, prompts, booking history, API keys) is scattered across the admin and the end-user /settings/* area, with no single place to see everything about a tenant at once.

This refactor restructures the admin around the tenant as the protagonist: an expandable top-level table of organizations and a dedicated per-tenant detail page consolidating config + stats.

After this sub-project:

/organizations shows one row per organization, expandable to reveal nested tenant rows.
/organizations/-/tenants/:id is a dedicated per-tenant page with stacked sections for every configuration area and a stats panel.
The prompt-customizations matrix is replaced by per-tenant prompt sections on the detail page.
Configuration that already has a dedicated page (costs, QA dataset, /settings/*) is linked to, not duplicated.

Scope

In scope:

New admin route structure under /organizations and /organizations/-/tenants/:id.
Expandable organization table with HTMX lazy loading.
Dedicated tenant detail page with 12 stacked sections (enumerated below).
Deletion of the prompt-customizations matrix from the top-level page.
Navigation cleanup: sidebar "Tenants" item renamed (post-rename: "Organizations").
Updates to existing admin tests where affected (only admin/ui/schema_form_test.clj if we touch schema_form.clj).

Out of scope:

New admin handler tests. Admin currently has no HTTP-handler tests; this sub-project does not establish the pattern.
Data model changes (done in SP1).
End-user /settings/* UI changes. The detail page links out to them unchanged.
Archival / soft-delete of organizations or tenants.
Admin RBAC changes.

Path	Purpose
`GET /organizations`	Top-level expandable list of organizations.
`POST /organizations`	Create organization (inline form).
`GET /organizations/-/generate-slug?name=...`	Auto-generate slug from name (existing pattern preserved).
`GET /organizations/:id`	Returns the edit modal for the organization.
`PUT /organizations/:id`	Save organization edits; response is the replacement `<tr>`.
`GET /organizations/:id/tenants`	Returns the expanded nested `<tr>` of tenant rows for an organization.
`POST /organizations/-/tenants`	Create tenant under selected organization.
`GET /organizations/-/tenants/:id`	Dedicated tenant detail page (full navigation, not a modal).
`PUT /organizations/-/tenants/:id`	Save tenant identity edits (inline on detail page).
`/organizations/-/tenants/:id/file-store*`	Unchanged — existing routes, reachable from the detail page.
`/organizations/-/tenants/:id/prompts*`	Unchanged — existing routes, reachable from the detail page.

No dedicated organization detail page. Organizations are thin: name, slug, member list. Identity is edited via modal. Member management already lives on /users. All substantive configuration belongs to tenants, which get the first-class page.

Top-level Table

Organization row (collapsed)

Column	Source
Expand chevron	—
Name	`organization.name`
Slug	`organization.slug`
Tenants	count of `tenant`
Users	count of `organization_membership`
Docs (last 30d)	aggregate `document` count across the org's tenants
Review backlog	aggregate `document WHERE needs_human_review = true`
Last activity	`MAX(document.updated_at)` across the org's tenants
Actions	edit (modal), create-tenant shortcut

Create form above the table (inline, existing pattern) posts to POST /organizations.

Expansion mechanism

Expand chevron triggers hx-get="/organizations/:id/tenants" targeting a placeholder <tr id="org-expansion-:id"> directly below the org row, hx-swap="outerHTML".
The response is a <tr><td colspan="N"> containing a nested <table> of tenant rows.
Collapsing: the same chevron (now in the expanded state) triggers a second hx-get returning the placeholder <tr> form, reversing the swap.
Lazy load: the top-level query fetches only org-level aggregates; tenant rows hit the DB only when an org is expanded.
No client-side JS beyond HTMX; expansion state is server-driven.

Nested tenant row columns

Column	Source
Name (link to detail page)	`tenant.name`
Country	`tenant.company_country`
Docs	`document` count
Review	`document WHERE needs_human_review = true` (red badge if > 0)
Sources	active / total `ap_doc_source` (e.g. `3/5`)
DATEV	✓ / – from `tenant_datev_integration.is_active`
Last activity	`MAX(document.updated_at)`

Clicking the name navigates to /organizations/-/tenants/:id.

Prompt-customizations matrix

Removed from the top-level /organizations page. Per-tenant prompt customizations move to the detail page (Section 6). Cross-tenant matrix view is not reproduced; we can add one later if it turns out to be missed.

Tenant Detail Page

/organizations/-/tenants/:id — full page with left-rail anchor navigation to the sections. Non-modal.

Breadcrumb: Organizations / <Organization Name> / <Tenant Name> (each crumb a link).
Tenant name, editable inline.
Quick-stats strip: docs, review backlog, active sources, DATEV status, token spend (last 30d), last activity.

Sections

Each section is a <section> with an id for anchor jumping; left-rail lists these anchors.

Identity & Company Info — editable inline: name, company address, VAT ID, tax ID, country. PUT-per-field on blur, following the inline-edit pattern already in use in the ERP UI.
Ingestion Sources — table of ap_doc_source rows for this tenant: address, provider, connection status, last sync, docs received, active flag. Create/edit delegated to the existing end-user /settings/* source-management page.
ERP Integration (DATEV) — status, company-name (from tenant_datev_integration.metadata), connected-by user, credential expiry. Link out to /settings/integrations for reconnection.
OAuth Integrations — Google Drive status + folder. Link out to /settings/google-drive.
Master Data — three subsections: GL accounts, cost centers, business partners. Each: row count, active status, last updated. Link out to /settings/data.
Prompt Customizations — each of the 8 prompt keys (extraction, vision, accounts-match, cost-center-match, accrual-match, tax-compliance, resolve-uncertain-validations, triage) with its current additions (if any) and an edit link to /organizations/-/tenants/:id/prompts?key=....
File Store (FP&A) — current backend + summary config. Link to /organizations/-/tenants/:id/file-store.
Notifications — channel count, workflow count. Link to /settings/notifications.
Booking History — latest upload, total items. Link to /settings/booking-history.
API Keys — list scoped to this tenant: prefix, name, permissions summary, created, last used, revoked status. Create/revoke inline (existing logic from admin/http/api_keys.clj, with the tenant filter pre-applied).
QA Dataset — counts by status (pending / approved / rejected). Link to /qa-dataset?tenant-id=<id>.
Stats / Cost — token usage last 30d (chart), OCR pages, ingestion success rate, avg processing time. Link to /costs?tenant-id=<id> for the full per-tenant cost dashboard.

Link-out vs duplicate

Sections that have an existing dedicated admin page (/costs, /qa-dataset, /api-keys) or end-user page (/settings/*) show a summary + link, not a duplicate configuration UI. Only identity and API keys are editable on the detail page; everything else is read-only summary + navigation to the canonical editor. This keeps the page scannable and avoids two sources of truth for the same config.

Hiccup and HTMX conventions

Follows the existing admin patterns documented in src/com/getorcha/admin/ui/:

section, card, stat-grid, data-table, status-badge from admin.ui.components.
Inline edits use OOB swaps to update stat strips when identity changes (e.g. renaming the tenant updates the breadcrumb crumb and the page title in the same response).
No new global CSS; reuse existing styles.

Testing

Admin has no HTTP-handler tests today. This sub-project does not introduce them. Only test touched: test/com/getorcha/admin/ui/schema_form_test.clj, and only if admin.ui.schema_form itself is modified (unlikely).

Manual verification:

Boot local system, visit /organizations, verify aggregate counts match direct DB queries for a sample org.
Expand an organization, verify nested tenant rows render with correct stats.
Navigate to a tenant detail page, walk every section, verify data matches the underlying tables.
Edit tenant identity inline, confirm OOB swap updates the breadcrumb.
Click every link-out, verify the linked page loads with the correct tenant context.

clj-kondo --lint src test dev clean.

Rollout

Merge after SP1 is live and stable.
No feature flag (admin-only).
The old /tenants → /organizations route map lands in SP1; SP2 builds on the new names directly.
Old matrix view deleted in the same PR.

Risks

Top-level query performance — the org row needs aggregate counts across its tenants. If orgs get large, this grows. Mitigation: the aggregates are simple COUNT joins on indexed FKs; fine up to thousands of tenants per org. Revisit if we hit a real problem.
HTMX expansion state across navigation — expanding an org, navigating to a tenant, then hitting back: default HTMX history may restore the collapsed state. Acceptable — expansion is cheap to redo.
Duplicate rendering if link-out targets change shape — if /settings/integrations moves or changes how it presents DATEV status, the summary on the detail page drifts. Mitigation: the summary pulls from the same DB tables, not from scraping the settings page; it won't drift due to UI changes there.

Follow-ups (not in this sub-project)

Organization-level prompt customization (if ever needed) — currently no such concept post-SP1.
Archive / soft-delete of tenants.
Per-tenant user permissions (today membership is org-scoped; users inherit access to all tenants in their org).
Cross-tenant prompt matrix view, if the absence turns out to matter.