kite/.planning/milestones/v0.2-phases/09-admin-panel-rearchitecture/09-CONTEXT.md

# Phase 9: Admin Panel Rearchitecture - Context

**Gathered:** 2026-06-12
**Status:** Ready for planning

<domain>
## Phase Boundary

Phase 9 delivers: (1) `AdminLayout.vue` registered as the `/admin` route component with its own sidebar and `<router-view />`; (2) each admin section extracted as a deep-linkable child route (`/admin`, `/admin/users`, `/admin/quotas`, `/admin/ai`, `/admin/audit`); (3) a new admin overview page at `/admin` showing platform stats + last 10 audit entries; (4) the `requiresAdmin` guard updated to protect all `/admin/*` children; (5) strict admin role separation — admin accounts are redirected to `/admin` on all user routes; (6) Tailwind safelist configured for dynamic `providerColor`/`providerBg`/`providerLabel` class patterns; (7) `AdminView.vue` and the original `AdminXxxTab.vue` components deleted; (8) CODE-09 comment purge pass over all Phase 9 files and retroactively over Phase 8 backend sub-packages.

</domain>

<decisions>
## Implementation Decisions

### Admin Overview Page (ADMIN-11)

- **D-01:** Layout: 3–4 stat cards in a top row (total users, total storage, document status breakdown: processing/ready/failed), followed by a table of the last 10 audit log entries below.
- **D-02:** Backend: new `overview.py` sub-module in `backend/api/admin/` alongside the existing `users.py`, `quotas.py`, `ai.py`. Single `GET /api/admin/overview` endpoint returning all four stats in one payload.
- **D-03:** Audit entries are inline in the aggregate response — the overview call returns stats + last 10 entries in one HTTP request. No separate `/api/audit` call from the overview component.

### Admin Sidebar Design (ADMIN-09 — PARTIAL OVERRIDE)

- **D-04:** SVG icons for each sidebar nav item — consistent with `AppSidebar.vue` pattern.
- **D-05:** Visual identity: subtle "Admin" label or badge below the DocuVault logo in the sidebar header. Same indigo brand color. No accent color change.
- **D-06:** **No "Back to app" link.** Admin role is administration-only. If an admin user needs to use the document app, they must have a separate normal user account. This overrides the ADMIN-09 requirement text that specified "Back to app link at bottom returns to /".
- **D-07:** Nav items (in order): Overview, Users, Quotas, AI Config, Audit Log. No "Back to app".

### Admin Role Strict Separation (NEW — not in original requirements)

- **D-08:** After login, if `user.role === 'admin'`, the router redirects to `/admin` instead of `/`.
- **D-09:** The `beforeEach` guard detects admin role on non-admin routes and redirects to `/admin`. Admin accounts cannot navigate to user routes (`/`, `/topics`, `/settings`, `/cloud`, etc.).
- **D-10:** Two guards in `beforeEach`: (a) non-admin attempting `/admin/*` → redirect to `/`; (b) admin attempting non-admin route → redirect to `/admin`. Both must use `to.matched.some(r => r.meta.requiresAdmin)` for the admin check (Vue Router 4 does not inherit meta to children).

### Tab Component Extraction (ADMIN-08, ADMIN-10)

- **D-11:** The four existing tab components (`AdminUsersTab.vue`, `AdminQuotasTab.vue`, `AdminAiConfigTab.vue`, `AuditLogTab.vue`) become standalone view files (`AdminUsersView.vue`, `AdminQuotasView.vue`, `AdminAiView.vue`, `AdminAuditView.vue`) in `frontend/src/views/admin/`. Extraction is structural only: strip top-level padding (owned by `AdminLayout`), rename, wire as router children.
- **D-12:** Original `components/admin/AdminXxxTab.vue` files are deleted after extraction — they become dead code. `AdminView.vue` is deleted.
- **D-13:** `AuditLogTab.vue` is promoted as-is. No new features, filters, or backend changes for the audit log view in Phase 9.

### Tailwind Safelist (CODE-06)

- **D-14:** Add `safelist` in `tailwind.config.js` covering `providerColor`, `providerBg`, `providerLabel` dynamic class patterns from `formatters.js`. Pattern from PITFALLS.md §14:
  ```js
  safelist: [
    { pattern: /bg-(blue|green|purple|orange|gray|indigo|red)-(50|100|500|600)/ },
    { pattern: /text-(blue|green|purple|orange|gray|indigo|red)-(500|600|700)/ },
  ]
  ```
  Researcher verifies which color families `formatters.js` actually uses and adjusts the pattern if needed.

### CODE-09 Comment Purge

- **D-15:** One dedicated plan at the end of Phase 9 covers all files touched in Phase 9 plus retroactive purge of Phase 8 backend sub-packages (`api/admin/`, `api/documents/`, `api/auth/`).
- **D-16:** Purge criterion: remove comments that describe WHAT code does (generic function docstrings, inline "this does X" comments). Keep comments that explain WHY: constraints, pitfall notes, non-obvious invariants (e.g., `api/admin/__init__.py`'s "sub-routers carry NO prefix" constraint stays; generic "Returns user list" docstrings go).

### Claude's Discretion

- Exact SVG icon choices for each admin sidebar nav item (researcher picks appropriate icons from the same icon family used in AppSidebar.vue)
- Exact Python queries for the overview aggregate endpoint (researcher reads `db/models.py` and determines the most efficient async query pattern)
- Naming of the new view files if `views/admin/` directory structure is adopted (researcher confirms directory convention)

</decisions>

<canonical_refs>
## Canonical References

**Downstream agents MUST read these before planning or implementing.**

### Phase Goals and Requirements
- `.planning/ROADMAP.md` §"Phase 9: Admin Panel Rearchitecture" — goal, implementation notes, success criteria, pitfall references
- `.planning/REQUIREMENTS.md` §ADMIN-08, ADMIN-09, ADMIN-10, ADMIN-11, ADMIN-12, CODE-06, CODE-09 — formal requirement definitions
- **Note:** ADMIN-09 "Back to app link" is overridden by D-06 and D-08 above. CONTEXT.md decisions take precedence.

### Vue Router 4 Admin Architecture
- `.planning/research/PITFALLS.md` §Pitfall 3 — `to.matched.some()` guard fix (security regression risk with flat `to.meta.requiresAdmin`)
- `.planning/research/PITFALLS.md` §Pitfall 4 — AdminLayout as route component, not App.vue v-else-if branch (double-render risk)
- `.planning/research/PITFALLS.md` §Pitfall 9 — double padding risk when extracting tab content into views with AdminLayout wrapper
- `.planning/research/PITFALLS.md` §Pitfall 14 — Tailwind purge of dynamic class names; safelist pattern

### Frontend Architecture
- `.planning/codebase/ARCHITECTURE.md` — component responsibilities, router guard, layout resolution pattern
- `frontend/src/App.vue` — current AuthLayout switch pattern (AdminLayout must NOT be added as a third branch here)
- `frontend/src/layouts/AuthLayout.vue` — reference pattern for a standalone layout component with `<router-view />`
- `frontend/src/router/index.js` — current guard and route structure being rearchitected
- `CLAUDE.md` §"Frontend: shared module map" — `formatters.js` is the single source for `providerColor`/`providerBg`/`providerLabel`
- `CLAUDE.md` §"Component architecture" — View → Smart → Presentational layering (admin views follow this)

### Backend Architecture
- `backend/api/admin/__init__.py` — existing admin package aggregator pattern; `overview.py` is added alongside existing sub-modules
- `backend/api/admin/users.py`, `quotas.py`, `ai.py` — reference for sub-module structure (overview.py follows same pattern)
- `backend/api/audit.py` — existing audit log implementation; overview endpoint reuses its query logic for last 10 entries
- `backend/db/models.py` — ORM models for users, quotas, documents (needed for aggregate queries)
- `CLAUDE.md` §"Key Architectural Rules" — admin endpoints never return document content or credentials_enc

### Existing Admin Components
- `frontend/src/views/AdminView.vue` — being deleted; contains current tab structure
- `frontend/src/components/admin/AdminUsersTab.vue` — being promoted to view
- `frontend/src/components/admin/AdminQuotasTab.vue` — being promoted to view
- `frontend/src/components/admin/AdminAiConfigTab.vue` — being promoted to view
- `frontend/src/components/admin/AuditLogTab.vue` — being promoted to view
- `frontend/src/utils/formatters.js` — dynamic class names that need safelist coverage

</canonical_refs>

<code_context>
## Existing Code Insights

### Reusable Assets
- `frontend/src/layouts/AuthLayout.vue` — exact pattern for a standalone layout: a plain `<template>` wrapper with `<router-view />` inside. `AdminLayout.vue` follows this same structure.
- `frontend/src/components/layout/AppSidebar.vue` — reference for SVG icon style, nav-link classes (`nav-link`, `nav-link-active`), logo/header structure, and sidebar dimensions (`w-64 bg-white border-r`). Admin sidebar reuses these classes.
- `backend/api/admin/__init__.py` — aggregator pattern: import sub-routers, register with parent. `overview.py` adds one more import line here.
- `backend/api/audit.py` — already has the paginated audit log query; `overview.py` reuses its query logic (limit=10) rather than duplicating it.

### Established Patterns
- `AdminLayout.vue` is the `/admin` route's `component:` — NOT a branch in `App.vue`. `App.vue` renders whatever the router resolves; it doesn't need to know about AdminLayout.
- `beforeEach` guard in `router/index.js` uses `to.matched.some(r => r.meta.requiresAdmin)` — the ONLY correct Vue Router 4 idiom for parent-meta inheritance on child routes. A plain `to.meta.requiresAdmin` check silently breaks for all child routes.
- Sub-routers in `api/admin/` carry NO `prefix` on `APIRouter()` — the parent carries `prefix="/api/admin"`. This constraint applies to `overview.py`.
- `api/admin/__init__.py` does ONLY router aggregation — no helpers, no models. `overview.py` houses the endpoint logic.

### Integration Points
- `frontend/src/router/index.js` — add `/admin` as a nested route with `AdminLayout` as component; add five children (`''`, `users`, `quotas`, `ai`, `audit`); update `beforeEach` guard with D-09/D-10 admin redirect logic; update login-redirect to send admin role to `/admin`.
- `frontend/src/App.vue` — no changes needed (AdminLayout handles its own layout; App.vue only needs the existing AuthLayout branch).
- `backend/api/admin/__init__.py` — add `from api.admin.overview import router as overview_router` and register it.
- `backend/main.py` — no changes needed (admin router registration unchanged).
- `frontend/src/stores/auth.js` — login action may need to check `user.role === 'admin'` and set redirect target to `/admin`.
- `frontend/tailwind.config.js` — add `safelist` array covering dynamic color patterns.

</code_context>

<specifics>
## Specific Ideas

- Admin overview layout: cards + table, not a full dashboard. Keep it simple — it's an operator utility page.
- Admin sidebar: "Admin" label/badge below "DocuVault" in header signals admin context without heavy visual changes.
- Strict role separation is a product decision: admin accounts are platform operators, not users. This is philosophically consistent with the privacy-first admin model already established in v0.1 (admin cannot read user documents or credentials).
- The overview endpoint returns everything in one payload — makes the AdminOverviewView.vue a single-fetch component with no coordination logic.

</specifics>

<deferred>
## Deferred Ideas

None — discussion stayed within phase scope.

</deferred>

---

*Phase: 9-Admin-Panel-Rearchitecture*
*Context gathered: 2026-06-12*