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

## 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.

## 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:

  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)

<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>

## 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.

## Deferred Ideas

None — discussion stayed within phase scope.

---

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