docs: define milestone v0.2 requirements (36 reqs, 6 categories)

UI overhaul, codebase quality, admin panel rearchitecture, UX
improvements, responsive layout, and performance/stack updates.
Research: STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.planning/research/PITFALLS.md

@@ -1,550 +1,290 @@
-# Pitfalls Research
+# Domain Pitfalls — v0.2 UI Overhaul and Optimization
 
-**Domain:** Multi-user SaaS document management platform (FastAPI + Vue 3, PostgreSQL + MinIO, cloud storage integrations)
-**Researched:** 2026-05-21
-**Confidence:** HIGH (auth/storage/multi-tenancy patterns are well-established; specific FastAPI + MinIO combination is MEDIUM — no web search available)
+**Project:** DocuVault
+**Milestone:** v0.2 — UI Overhaul and Optimization on existing FastAPI + Vue 3 app
+**Researched:** 2026-06-07
+**Confidence:** HIGH (all pitfalls grounded in actual source files: router/index.js, App.vue, main.py, client.js, StorageBrowser.vue, DocumentCard.vue, DropZone.vue, AppSidebar.vue, and all api/*.py router files)
 
 ---
 
 ## Critical Pitfalls
 
-### Pitfall 1: JWT in localStorage — XSS Gives Full Account Takeover
+Mistakes that cause regressions, security gaps, or rewrites.
+
+---
+
+### Pitfall 1: FastAPI Router Splitting — Prefix Already Embedded in APIRouter, Not in include_router
+
+**Phase:** Backend refactoring (split large router files)
+
+**What goes wrong:** Every existing router in this codebase declares its prefix on the `APIRouter` instance itself — `router = APIRouter(prefix="/api/documents", tags=["documents"])` — NOT on the `include_router(router, prefix=...)` call in `main.py`. When splitting a large file (e.g. `documents.py` at 852 lines, `admin.py` at 934 lines) into sub-modules, the new sub-routers pick up their endpoints via an `include_router` call inside the original module, or they are wired directly in `main.py`. Either way, if you add a prefix on `include_router` in addition to the prefix on the inner `APIRouter`, all URLs double-prefix to `/api/documents/api/documents/...`. Likewise, if you strip the prefix from the inner router and forget to add it to `include_router`, all URLs return 404.
+
+**Why it happens:** The original pattern (`router = APIRouter(prefix=...)` in the module + `app.include_router(router)` without a prefix in `main.py`) is unusual but consistent in this project. Developers splitting a file expect the standard pattern where prefixes go on `include_router`, not on the router definition.
+
+**Consequences:** 404 on all endpoints in the split module; existing tests and the frontend `client.js` (which hard-codes `/api/documents`, `/api/admin`, etc.) silently break.
+
+**Prevention:** When splitting, create sub-routers with NO prefix: `sub = APIRouter(tags=["documents-upload"])`. Register them inside the parent module with `router.include_router(sub)` so the parent's prefix propagates. The parent module keeps its existing prefix and its existing `app.include_router(parent)` call in `main.py` is unchanged.
+
+**Detection warning signs:** Any test that calls `/api/documents/*` returns 404 immediately after the split; Swagger UI shows doubled path segments.
+
+---
+
+### Pitfall 2: FastAPI Router Splitting — Circular Import via Shared Dependencies
+
+**Phase:** Backend refactoring
+
+**What goes wrong:** `folders.py` already exports a `document_move_router = APIRouter(prefix="/api/documents")` — a cross-cutting concern documented in the file (line 439-442). When splitting `documents.py`, if the new sub-module imports anything from `api/folders.py` (e.g. a shared validator or Pydantic schema), Python raises `ImportError: cannot import name X` at startup because both modules are in partial initialization state.
+
+**Why it happens:** FastAPI modules that share models and validators tend to grow cross-references. The `document_move_router` in `folders.py` under the `/api/documents` prefix is the existing example — any new import in the opposite direction closes the import cycle.
+
+**Consequences:** Application fails to start. Docker container exits immediately.
+
+**Prevention:** Shared Pydantic models and validators must live in `db/models.py` or a dedicated `schemas/` module — not in router files. Before splitting, grep for any `from api.X import` inside the router files being split and move the shared symbols to a neutral module first.
+
+**Detection warning signs:** `ImportError` or `cannot import name` in the uvicorn startup log.
+
+---
+
+### Pitfall 3: AdminLayout Vue Router Integration — beforeEach Guard Misses /admin/* Children
+
+**Phase:** Admin panel rearchitecture
+
+**What goes wrong:** The current guard in `router/index.js` (lines 81-93) checks `to.meta.requiresAdmin` on the matched route object. The current `/admin` route is a flat route with that meta set directly. When `/admin` becomes a parent route with nested children (`/admin/users`, `/admin/audit`, etc.), the children do NOT automatically inherit `meta: { requiresAdmin: true }` from the parent in Vue Router 4 unless the guard iterates `to.matched`. If the children are added without repeating the meta, the guard's `to.meta.requiresAdmin` check evaluates to `undefined` (falsy) for every child route — non-admin users can navigate to `/admin/users` directly.
+
+**Why it happens:** Vue Router 4 does NOT merge parent `meta` into child `meta` by default. `to.meta` reflects only the deepest matched route's own meta, not the parent's.
+
+**Consequences:** Security regression — the admin guard that currently works correctly stops protecting all admin child routes. Non-admin users can access `/admin/users`, `/admin/audit`, etc.
+
+**Prevention:** Update the guard to check `to.matched.some(r => r.meta.requiresAdmin)` instead of `to.meta.requiresAdmin`. This is the correct Vue Router 4 idiom for inherited meta and requires one change to the guard. Apply the same fix to the `!to.meta.public` check if any auth routes gain children.
+
+```javascript
+// router/index.js — change:
+if (to.meta.requiresAdmin && authStore.user?.role !== 'admin') {
+// to:
+if (to.matched.some(r => r.meta.requiresAdmin) && authStore.user?.role !== 'admin') {
+```
+
+---
+
+### Pitfall 4: AdminLayout Integration — App.vue Layout Switch Breaks for /admin/* Routes
+
+**Phase:** Admin panel rearchitecture
+
+**What goes wrong:** `App.vue` currently switches between `AuthLayout` (when `route.meta.layout === 'auth'`) and the main app shell (sidebar + `<router-view>`) for everything else. The admin panel needs a third layout (`AdminLayout`) with its own nav. The naive approach — `v-else-if="route.meta.layout === 'admin'"` in `App.vue` rendering `AdminLayout` which then renders `<router-view />` — creates double rendering: `App.vue`'s `<router-view>` already resolved the full route. The inner `<router-view>` inside `AdminLayout` gets nothing because the route is already consumed.
+
+**Consequences:** Admin layout renders with an empty content area, or the admin page renders without the admin chrome.
+
+**Prevention:** The correct structure for a standalone admin layout in Vue Router 4:
+
+```javascript
+// router/index.js
+{
+  path: '/admin',
+  component: AdminLayout,   // resolves to the layout shell, which contains <router-view />
+  meta: { requiresAdmin: true },
+  children: [
+    { path: '', redirect: '/admin/users' },
+    { path: 'users', component: AdminUsersView },
+    { path: 'quotas', component: AdminQuotasView },
+    { path: 'ai', component: AdminAiView },
+    { path: 'audit', component: AdminAuditView },
+  ]
+}
+```
+
+`AdminLayout.vue` contains `<router-view />` where page content renders. `App.vue` remains unchanged — it renders the component that the route resolves to, which is now `AdminLayout`. No third branch in `App.vue` is needed.
+
+---
+
+### Pitfall 5: client.js Splitting — noRefreshPaths Breaks When Paths Move to Sub-modules
+
+**Phase:** Frontend refactoring (client.js split)
+
+**What goes wrong:** `client.js` has a hardcoded `noRefreshPaths` list inside `request()` (line 26) that guards against infinite refresh loops. If `request()` is moved to a shared `api/core.js` module and the path list stays there, it works. But the three blob-download functions (`adminExportAuditLogCsv`, `adminDownloadDailyExport`, `fetchDocumentContent`) each contain a duplicated copy of the 401-refresh-retry logic. When splitting `client.js` into domain files, those duplicates will be copied into new sub-files. This is the correct moment to eliminate them — but if missed, the bug surface multiplies.
+
+**Additionally:** If components are changed to import from sub-files directly (e.g. `import { listDocuments } from '../api/documents.js'`) instead of the barrel, every other component that imports from `client.js` still works — but a future refactor that renames a function in the sub-file will miss the barrel re-export and break components that still use the barrel. Both import paths exist simultaneously and diverge.
+
+**Prevention:** Split in this order:
+1. Extract `request()` + `noRefreshPaths` into `api/core.js`. Export `request` from there.
+2. Extract the 401-retry pattern from the three blob-download functions into a single `fetchWithRetry(url, headers)` helper also in `api/core.js`.
+3. Create domain files (`api/documents.js`, `api/admin.js`, `api/auth.js`, etc.) that import from `api/core.js`.
+4. Keep `api/client.js` as a re-export barrel: `export * from './documents.js'; export * from './admin.js'` etc. This preserves all existing `import { listDocuments } from '../api/client.js'` calls without touching any component. Never change component imports to point at sub-files directly.
+
+---
+
+### Pitfall 6: Drag-and-Drop on DocumentCard — dragstart vs @click Conflict
+
+**Phase:** UX improvements (drag-and-drop)
+
+**What goes wrong:** `DocumentCard.vue` navigates on `@click="$router.push('/document/' + doc.id)"` (line 4). Browsers fire `click` after `dragend` when the drag distance is below the browser's drag-initiation threshold — typically ~4px. A user who clicks and releases without moving far enough triggers both `dragstart` and then `click`: the card navigates to the document even though the user intended to start a drag.
+
+**Also:** The action buttons inside `DocumentCard` use `@click.stop`. If a drag handle overlaps an action button area, `@click.stop` prevents the click from propagating but does not prevent `dragstart` from bubbling — behavior becomes inconsistent depending on which pixel the user starts from.
+
+**Note:** `StorageBrowser.vue` already implements drag-and-drop on list rows correctly (lines 141-145: `draggable`, `@dragstart`, `@dragend`) and does not have this problem because the row's `@click` emits `file-open` rather than navigating imperatively. The risk is specific to adding drag to `DocumentCard.vue` (card grid used in `TopicsView`).
+
+**Prevention:**
+1. Track drag state with a component-level `dragging` ref. Set `dragging = true` in `@dragstart`, reset to `false` in `@dragend`. Guard `@click`: `if (this.dragging) return`.
+2. Preferred: use a dedicated drag handle element (grip icon, `cursor-grab`) and set `draggable="true"` only on that element. Add `@click.stop` on the handle. The rest of the card retains click-to-navigate.
+
+---
+
+### Pitfall 7: Virtual Scrolling — StorageBrowser DOM Assumptions Break
+
+**Phase:** Frontend performance (virtual scrolling)
 
 **What goes wrong:**
-The Vue 3 SPA stores the JWT access token in `localStorage`. Any JavaScript injected via XSS (in file names, document content previewed in the UI, a compromised dependency) can call `localStorage.getItem('token')` and exfiltrate a long-lived credential. The attacker then impersonates the user from any origin, bypasses TOTP entirely (the token is post-authentication), and can access all documents, including cloud storage credentials.
 
-**Why it happens:**
-`localStorage` is the path of least resistance in SPAs. It survives page reloads, works with Axios interceptors trivially, and requires no server-side session state. FastAPI tutorials almost universally use `Authorization: Bearer` headers set from localStorage.
+`StorageBrowser.vue` renders its item list with `divide-y divide-gray-100` (line 76). The Tailwind `divide-y` utility inserts borders using adjacent-sibling CSS (`& > * + * { border-top-width: 1px }`). This only works when all children are present in the DOM simultaneously. Virtual scroll libraries keep only visible rows in the DOM — `divide-y` produces borders only between the visible subset, leaving gaps at virtual boundaries.
 
-**How to avoid:**
-- Issue the JWT as an **httpOnly, SameSite=Strict, Secure cookie** — JavaScript cannot read it.
-- Use a short-lived access token (15 minutes) in the httpOnly cookie.
-- Issue a separate refresh token (httpOnly cookie, longer TTL, `/auth/refresh` path-scoped) to rotate access tokens silently.
-- The Vue frontend never holds the raw token string. Axios is configured with `withCredentials: true`; the browser attaches cookies automatically.
-- CSRF protection: because `SameSite=Strict` blocks cross-site cookie submission, CSRF tokens are not strictly required for same-origin SPAs, but add a CSRF header check (`X-Requested-With: XMLHttpRequest`) as defence-in-depth.
+The folder picker dropdown inside file rows (lines 185-213) is `absolute right-0 top-full` — positioned relative to its parent row. Virtual scroll repositions rows via `transform: translateY()`. Absolutely positioned children escape their transformed parent and appear at wrong viewport positions.
 
-**Warning signs:**
-- `localStorage.getItem` anywhere in auth-related frontend code
-- JWT decode functions in frontend code (the frontend should not need to decode a token it can't read)
-- `Authorization: Bearer ${token}` header set manually in Axios interceptor
+CSS transitions on rows (`transition-all`, `transition-colors`) work with `v-for` because Vue animates DOM insertion/removal. Virtual scroll does not insert/remove — it repositions. Vue's `<transition-group>` cannot wrap a virtually scrolled list and will throw warnings.
 
-**Phase to address:** Auth phase (Phase 1 — Users & Auth)
+**Prevention:**
+1. Replace `divide-y` with `border-b border-gray-100` on each individual row element. Rows become self-contained and do not depend on DOM adjacency.
+2. The folder picker dropdown must use `<Teleport to="body">` with `position: fixed` coordinates computed from `getBoundingClientRect()`. This is a prerequisite for virtual scroll adoption, not optional.
+3. Remove any `<transition-group>` wrapping a virtually scrolled list. Use per-row fade-in via a CSS class added on first mount instead.
 
 ---
 
-### Pitfall 2: TOTP Bypass via Password Reset Flow
-
-**What goes wrong:**
-The password reset flow issues a one-time token by email. After the user resets their password, the system logs them in and redirects to the dashboard — skipping the TOTP prompt because the session was created through the reset path, not the login path. An attacker who compromises a user's email account can therefore completely bypass TOTP.
-
-**Why it happens:**
-Password reset and login are treated as separate code paths. The TOTP check lives in the login handler; the reset handler creates a session directly after credential update without going through the TOTP gate.
-
-**How to avoid:**
-- After a successful password reset, issue a partial session or a `password_reset_pending` state, not a full authenticated session.
-- Force the user to complete the full login flow (including TOTP if enabled) from the new credentials.
-- Alternatively, on password reset completion, invalidate all existing sessions and send the user to the login page (no auto-login).
-- Log password resets in the audit trail with IP and user-agent.
-
-**Warning signs:**
-- Password reset handler calls the same session-creation function as login but omits 2FA state checks
-- No `mfa_verified` flag on sessions (only `authenticated`)
-- Users can reach protected endpoints via a token created from the reset path
-
-**Phase to address:** Auth phase (Phase 1 — Users & Auth)
+## Moderate Pitfalls
 
 ---
 
-### Pitfall 3: Refresh Token Rotation — Stolen Refresh Token Not Detected
+### Pitfall 8: Responsive Layout — w-64 Sidebar vs Flex-1 Content on Mobile
 
-**What goes wrong:**
-Refresh tokens are issued as single-use rotating credentials. If an attacker steals a refresh token and uses it before the legitimate user does, the server rotates the token and the attacker has a valid new one. The legitimate user's next refresh request fails — but without a detection mechanism the failure just looks like a session expiry, no alert is raised, and the attacker continues with the stolen session indefinitely.
+**Phase:** Responsive / mobile layout
 
-**Why it happens:**
-Teams implement the "rotate on use" mechanic without implementing the "revoke family on reuse" detection. The `refresh_tokens` table lacks a `family_id` column linking reissued tokens.
+**What goes wrong:** `App.vue` uses `flex h-screen overflow-hidden` with `AppSidebar` fixed at `w-64 shrink-0`. On screens narrower than ~320px the content area collapses below usable width. `StorageBrowser`'s 5-column grid `grid-cols-[2rem_1fr_6rem_8rem_6rem]` has `hidden sm:block` and `hidden md:block` to hide size and date columns — but the fixed `2rem` icon and `6rem` action columns still consume 128px on either side of the filename, leaving minimal space on a 375px screen.
 
-**How to avoid:**
-- Store refresh tokens in the database with a `family_id` (UUID for the original issuance chain) and a `revoked` flag.
-- When a refresh token is presented: if it is already marked `revoked` (i.e., a previously rotated token), revoke the **entire family** — force logout of all sessions for that user.
-- Emit a security alert (audit log + optionally email) when a reuse attempt is detected.
-- Refresh tokens should be hashed before storage (bcrypt or SHA-256 with a per-row salt), same as passwords.
-
-**Warning signs:**
-- Refresh tokens stored as plain values in DB with no `revoked` column
-- No `family_id` linking related rotation chains
-- Stolen refresh token detection treated as "v2 feature"
-
-**Phase to address:** Auth phase (Phase 1 — Users & Auth)
+**Prevention:**
+1. On mobile (`< lg`), hide the sidebar. Use a hamburger button in a mobile-only header bar. Toggle with `translate-x-0 / -translate-x-full` transition on the sidebar element.
+2. The sidebar open/closed state needs to be in a Pinia store ref (or provided from `App.vue`) so the hamburger button in the header, the sidebar overlay, and the main content area all react to it. Do not put it in a component's `data()`.
+3. On mobile, simplify the grid to `grid-cols-[2rem_1fr_4rem]` — filename and a single action column. Test at 375px explicitly.
 
 ---
 
-### Pitfall 4: TOTP — Timing Attack on Code Verification
+### Pitfall 9: Admin Panel + Responsive — Double Padding After Extracting Tab Content
 
-**What goes wrong:**
-TOTP verification uses Python `==` string comparison. Python's `==` on strings is not constant-time — it short-circuits on the first differing character. A sufficiently sophisticated timing oracle (millions of requests from a local network) can distinguish valid from invalid codes, reducing the 6-digit brute-force space. More practically: without rate limiting, an attacker can brute-force all 1,000,000 possible 6-digit codes during a 30-second window.
+**Phase:** Admin panel rearchitecture + responsive layout (interaction pitfall)
 
-**Why it happens:**
-TOTP libraries (PyOTP) return a string; developers do `if provided == expected`. Rate limiting is added "later" and often never lands.
+**What goes wrong:** `AdminView.vue` wraps all content in `p-8 max-w-5xl mx-auto`. Each tab component (`AdminUsersTab.vue`, `AdminQuotasTab.vue`, etc.) has its own internal padding. When tab components are extracted into standalone page views (`AdminUsersView.vue`, etc.), the `p-8 max-w-5xl mx-auto` wrapper moves to `AdminLayout.vue`. If the extracted page views retain their own inner padding, content is double-padded. If `AdminLayout` does not include the constraint, the new admin pages render full-bleed against the viewport.
 
-**How to avoid:**
-- Use `hmac.compare_digest(provided, expected)` instead of `==` for TOTP comparison.
-- Rate-limit TOTP attempts: 5 attempts per 30-second window, 15-minute lockout on excess.
-- The lockout must be stored server-side (Redis or DB), not client-side.
-- Accept only the current window and optionally ±1 window for clock drift — do not accept wider ranges.
-- Log every failed TOTP attempt with IP.
-
-**Warning signs:**
-- `if totp.verify(code):` without inspecting PyOTP's internal comparison method
-- No rate limit on `POST /auth/totp/verify`
-- TOTP window set to 2+ (default is ±1 window = 90 seconds valid — wider than needed)
-
-**Phase to address:** Auth phase (Phase 1 — Users & Auth)
+**Prevention:** When extracting tab components into page views, strip all top-level padding and `max-w` from the extracted component — those belong to `AdminLayout`'s content area. The page components should fill 100% of the space provided by the layout slot.
 
 ---
 
-### Pitfall 5: Path Traversal in User File Access (MinIO Object Keys)
+### Pitfall 10: Options API Refactoring — Prop Mutation via v-model
 
-**What goes wrong:**
-MinIO object keys are constructed from user input: `f"users/{user_id}/{filename}"`. If `filename` contains `../`, `../../`, or URL-encoded equivalents (`%2e%2e%2f`), the resulting key may escape the user's prefix and land in another user's namespace. A request for `../../other_user_id/secret.pdf` resolves to `users/other_user_id/secret.pdf`.
+**Phase:** Frontend refactoring (Vue component decomposition)
 
-**Why it happens:**
-Developers trust that MinIO will sanitize paths. It does not — S3-compatible APIs treat object keys as arbitrary strings. The prefix-based isolation is only as safe as the key construction code.
+**What goes wrong:** If a component receives a prop and binds it directly to `<input v-model="propName">`, Vue emits a prop mutation warning in development. In production (no warnings), the mutation silently fails to propagate: the component's displayed value updates (local vdom), but the parent never receives the change because no `update:propName` event was emitted.
 
-**How to avoid:**
-- Never use raw filenames as object key components. Generate a UUID (or UUID + original extension) as the stored key: `f"users/{user_id}/{uuid4()}{ext}"`.
-- Store the human-readable filename in the database metadata row, completely decoupled from the storage key.
-- If filenames must appear in keys for any reason, strip or reject any `/`, `\`, `..`, `%` characters before key construction.
-- On retrieval, look up the object key from the database row (which is owned by `user_id`) rather than constructing it from user input.
+**Specific risk in this codebase:** `AdminUsersTab`, `AdminQuotasTab`, and `AuditLogTab` currently own their filter/search state internally. When extracted into standalone views, these may receive initial state from route query params and accidentally bind those props directly to inputs.
 
-**Warning signs:**
-- `object_key = f"users/{user_id}/{request.filename}"`
-- File download endpoint accepts a `path` or `filename` query parameter and constructs the key from it
-- No database lookup intermediating between "user requests file" and "MinIO key used"
-
-**Phase to address:** Storage migration phase (Phase 2 — DB + MinIO migration)
+**Prevention:** Any input the component controls must bind to a local `data()` copy initialized from the prop: `data() { return { localFilter: this.initialFilter } }`. Emit `update:initialFilter` on change. Never write `v-model="$props.X"`.
 
 ---
 
-### Pitfall 6: Quota Race Condition — Concurrent Uploads Bypass the Limit
+### Pitfall 11: Options API Refactoring — data() vs computed() in Decomposed Components
 
-**What goes wrong:**
-Two upload requests arrive simultaneously for a user at 99 MB of a 100 MB quota. Both read quota usage as 99 MB, both pass the `99 + 1 < 100` check, both proceed to upload — the user ends at 101 MB. At larger scale (many simultaneous large uploads) the overage can be significant.
+**Phase:** Frontend refactoring
 
-**Why it happens:**
-Quota enforcement is implemented as: read current usage → check → write file → update usage. This is a classic check-then-act race when the check and the write are not atomic.
+**What goes wrong:** When extracting a large component, logic that was a `computed()` in the parent often gets copy-pasted into a child's `data()`. A `data()` value initializes once at mount — it does not react to prop changes. If the parent later passes a different prop value (e.g. the document list changes after a search), the child's stale `data()` copy never updates.
 
-**How to avoid:**
-- Enforce quota atomically using a `SELECT ... FOR UPDATE` on the quota row before uploading, or use a PostgreSQL advisory lock keyed on `user_id`.
-- Better: use an optimistic update: `UPDATE quotas SET used_bytes = used_bytes + $new WHERE user_id = $uid AND used_bytes + $new <= limit_bytes RETURNING used_bytes`. If 0 rows are updated, the quota was exceeded — reject before touching MinIO.
-- Only update `used_bytes` after the MinIO upload succeeds, but hold the lock/reservation through the upload, or use a two-phase: reserve bytes → upload → confirm, with a cleanup job for stuck reservations.
-- Never read quota, do arithmetic in Python, then write back as two separate statements.
-
-**Warning signs:**
-- `current = get_quota(user_id); if current + size <= limit: upload()`
-- No database transaction wrapping quota check and update
-- Quota table updated with `SET used_bytes = $computed_value` (full overwrite) rather than `used_bytes + delta`
-
-**Phase to address:** Storage migration phase (Phase 2 — DB + MinIO migration) and Quotas phase
+**Prevention:** For every value in a newly created component, ask: "If the parent passes a different value for this prop, should the child update?" Yes → `computed()`. No → `data()`. Initialized from prop but locally modified afterward → `data()` with a `watch` on the prop to reset when it changes externally.
 
 ---
 
-### Pitfall 7: Admin Privilege Escalation via Missing Ownership Checks
+### Pitfall 12: Keyboard Shortcuts — Conflict with Text Inputs and Browser Defaults
 
-**What goes wrong:**
-An admin API endpoint is gated on `is_admin=True` but document-access endpoints only check `is_authenticated`. An admin user calling `GET /api/documents/{id}` with any document ID can read any user's document because the handler checks authentication but not `document.owner_id == current_user.id`. The privacy-first model is violated without any special exploit — just a correctly authenticated request.
+**Phase:** UX improvements (keyboard shortcuts)
 
-**Why it happens:**
-Authorization is implemented as authentication + role checks ("is this user an admin?") without resource-level ownership verification ("does this user own this resource?"). FastAPI dependency injection makes it easy to write `current_user = Depends(get_current_user)` and forget to check `resource.user_id == current_user.id`.
+**What goes wrong:** A global `keydown` listener on `window` fires regardless of focused element. Shortcuts like `/` (focus search), `n` (new folder), `Delete` (delete selected) are also typed characters. They must not fire when any `<input>`, `<textarea>`, `<select>`, or `[contenteditable]` element has focus. `Escape` conflicts with native `<dialog>` cancel events if `DocumentPreviewModal` uses a native dialog — both fire, causing a double-close bug.
 
-**How to avoid:**
-- Every document/file/folder endpoint must assert `resource.user_id == current_user.id` (or check share grants). This check cannot be optional or deferred.
-- Admins access user account metadata via separate admin-scoped endpoints that explicitly exclude document content, file URLs, and cloud credentials.
-- Write a test: log in as admin, attempt `GET /documents/{document_owned_by_other_user}`, assert `403`.
-- Use a centralized `assert_document_access(document, current_user)` function rather than inline checks to prevent omissions.
+**Prevention:**
 
-**Warning signs:**
-- Document endpoints that check `if not current_user` but not `if document.user_id != current_user.id`
-- Admin endpoints that return document content or presigned URLs
-- No explicit tests for cross-user access attempts
+```javascript
+function onKeydown(e) {
+  const tag = document.activeElement?.tagName
+  const isEditing = ['INPUT', 'TEXTAREA', 'SELECT'].includes(tag)
+    || document.activeElement?.isContentEditable
+  if (isEditing) return
 
-**Phase to address:** Auth phase (Phase 1) and every subsequent phase that adds resource-access endpoints
+  if (e.key === '/' && !e.ctrlKey && !e.metaKey) {
+    e.preventDefault()
+    searchInputRef.value?.focus()
+  }
+}
+// Options API: register in mounted(), remove in beforeUnmount()
+// Omitting the removeEventListener is the most common bug in this pattern.
+```
+
+Never call `preventDefault()` on `F5`, `Backspace`, `Ctrl+F`, or `Cmd+F` — these are browser-reserved. Use a Pinia store to track which shortcut context is active (file manager, document view, modal) so modal shortcuts suppress file manager shortcuts rather than both firing.
 
 ---
 
-### Pitfall 8: Cloud Credential Leakage via Admin Query
-
-**What goes wrong:**
-Cloud storage credentials (OAuth tokens, Nextcloud passwords) are encrypted at rest. But a query like `SELECT * FROM cloud_connections WHERE user_id = $uid` returns the ciphertext. If an admin dashboard endpoint runs this query and serializes the full row to JSON, the ciphertext ships to the admin browser. An admin cannot decrypt it without the key — but the ciphertext is now in browser history, proxy logs, and admin audit records. If the encryption key is later exposed, all credentials decrypt retroactively.
-
-**Why it happens:**
-ORM models serialize all columns by default. Developers add `encrypted_credentials` to the model and forget to exclude it from admin-facing serializers.
-
-**How to avoid:**
-- The `cloud_connections` table's credential column (`encrypted_token`, `encrypted_refresh_token`) must be **excluded** from all serialization by default.
-- Use explicit Pydantic response models for every endpoint — no `orm_mode` with full model pass-through.
-- Admin endpoints for cloud connections return only: `provider`, `account_label`, `connected_at`, `last_used_at`, `status` — never the credential column, not even ciphertext.
-- Audit log cloud credential access separately: the only code path that should ever read the encrypted column is the storage adapter, not admin or user-info endpoints.
-
-**Warning signs:**
-- `CloudConnection` Pydantic schema includes `encrypted_token` field
-- Admin user-detail endpoint returns full cloud connection rows
-- ORM model uses `model_config = ConfigDict(from_attributes=True)` without explicit field exclusions
-
-**Phase to address:** Cloud storage integration phase (Phase 3 or 4)
+## Minor Pitfalls
 
 ---
 
-### Pitfall 9: Flat-file to PostgreSQL Migration — Data Loss During Cutover
+### Pitfall 13: Loading Skeletons — Count Mismatch Causes Layout Shift
 
-**What goes wrong:**
-The migration script reads all JSON files, transforms them to DB rows, and then a flag switches the app to use PostgreSQL. Documents uploaded during the migration window are written to the old JSON store (because the flag has not flipped yet) and are missed by the migration script, which ran before they arrived. After cutover, those documents are invisible.
+**Phase:** UX improvements (loading skeletons)
 
-**Why it happens:**
-Migrations are planned as offline events ("we'll take the app down for 5 minutes") and then discovered to be impractical — the app is used 24/7 or downtime feels risky. The team runs the migration online without dual-write.
+**What goes wrong:** `StorageBrowser.vue` already has a `loading` prop (line 244) that shows "Loading…" text. Replacing this with skeleton rows requires a skeleton count. Hardcoding 5 rows when `per_page=20` causes a jump; using `per_page` as the skeleton count when only 3 items exist also jars. If skeleton rows are different heights from actual rows, the layout shifts when real content loads — this is a Core Web Vitals issue.
 
-**How to avoid:**
-- Plan the migration in three phases:
-  1. **Dual-write**: deploy code that writes to both JSON and PostgreSQL, reads from JSON. All new documents land in both stores.
-  2. **Backfill**: run migration script to copy historical JSON records to PostgreSQL. New records are already there.
-  3. **Cutover**: flip read source to PostgreSQL, verify counts match, remove JSON write path.
-- The dual-write window can be as short as one deployment cycle.
-- Include a reconciliation check: `assert doc_count_json == doc_count_db` before cutting over.
-- Keep the old JSON store read-only for 1 week post-cutover as a rollback option.
-
-**Warning signs:**
-- Migration is planned as "take app down, run script, bring back up"
-- No count-reconciliation step
-- No rollback plan documented before migration begins
-
-**Phase to address:** DB + MinIO migration phase (Phase 2)
+**Prevention:** Render skeletons at the previous page's actual item count (stored in the parent store). Default to 6-8 on first load. Skeleton rows must match the height of `StorageBrowser`'s actual grid rows exactly — use the same `px-4 py-2.5 grid-cols-[2rem_1fr_6rem_8rem_6rem]` structure with gray placeholder blocks.
 
 ---
 
-### Pitfall 10: Blocking I/O Inside Async FastAPI Handlers (Existing Issue)
+### Pitfall 14: Tailwind Purging — Dynamic Class Names in Refactored Components
 
-**What goes wrong:**
-The codebase already uses synchronous `filelock` and `open()` inside `async def` handlers (CONCERNS.md item 6). After migration to PostgreSQL + MinIO, if synchronous DB drivers (psycopg2) or synchronous MinIO client calls replace the file I/O without wrapping in `asyncio.to_thread()`, the event loop stalls on every I/O operation. Under concurrent load (multiple users uploading), requests queue behind each other even though the hardware is idle.
+**Phase:** Visual redesign (Tailwind component system)
 
-**Why it happens:**
-SQLAlchemy sync engine + psycopg2 is the default FastAPI tutorial stack. The MinIO Python SDK (`minio` package) is synchronous. Developers add `await` in front of calls that are not coroutines, get a type error, remove the `await`, and ship blocking code.
+**What goes wrong:** Vite + Tailwind purges unused CSS at build time by scanning template strings for class names. Dynamic class names constructed at runtime (e.g. `'text-' + color + '-500'`) are invisible to the purger. In development all classes are present; in production the dynamic classes are stripped and topics/provider badges render without color.
 
-**How to avoid:**
-- Use SQLAlchemy async engine with `asyncpg` driver: `create_async_engine("postgresql+asyncpg://...")`.
-- Wrap all MinIO SDK calls in `asyncio.to_thread()` since there is no official async MinIO client: `await asyncio.to_thread(minio_client.put_object, ...)`.
-- Alternatively use `aioboto3` (async boto3) which works with MinIO's S3-compatible API.
-- `aiofiles` is already in `requirements.txt` — use it for any remaining local file operations.
-- Run `pytest-asyncio` + `asyncio.get_event_loop().set_debug(True)` in tests; the debug mode logs blocking calls.
+**Specific risk:** `formatters.js` functions `providerColor`, `providerBg`, `providerLabel` return class strings. If those strings are not present as complete literals anywhere in the scanned source, they are purged.
 
-**Warning signs:**
-- `from sqlalchemy import create_engine` (not `create_async_engine`)
-- `import psycopg2` anywhere in application code
-- `minio_client.put_object(...)` not wrapped in `asyncio.to_thread`
-- Uvicorn logs show high request latency even with low CPU usage
-
-**Phase to address:** DB + MinIO migration phase (Phase 2)
+**Prevention:** Add a `safelist` in `tailwind.config.js`:
+```javascript
+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)/ },
+]
+```
+Alternatively, use a lookup object of complete class strings rather than string concatenation — Tailwind can scan complete strings in object literals.
 
 ---
 
-### Pitfall 11: N+1 Queries on Document Listing
-
-**What goes wrong:**
-`GET /api/documents` returns a list of documents, each including folder name, topic names, and share count. The handler fetches the document list, then for each document issues separate queries for folder, topics, and shares. 100 documents = 301+ queries per page load. The existing codebase already has an O(N) disk scan equivalent (CONCERNS.md items 8, 9); the PostgreSQL migration preserves this pattern if not corrected.
-
-**Why it happens:**
-SQLAlchemy lazy loading is the default. `document.folder.name` triggers a query. Developers don't see it until production load hits.
-
-**How to avoid:**
-- Use SQLAlchemy `joinedload` or `selectinload` options on the document list query to eagerly load related entities.
-- The list endpoint should be a single SQL query with JOINs, not a loop.
-- Add `EXPLAIN ANALYZE` checks as part of the phase acceptance criteria.
-- Enable SQLAlchemy `echo=True` in development to log every SQL statement.
-- Pagination at the database level: `LIMIT 50 OFFSET $n` — not "fetch all, slice in Python."
-
-**Warning signs:**
-- SQLAlchemy models using default relationship loading without explicit `lazy=` options
-- `for doc in documents: doc.folder.name` pattern
-- No `joinedload` or `selectinload` in list query definitions
-- Query count in tests grows linearly with fixture size
-
-**Phase to address:** DB + MinIO migration phase (Phase 2); enforce in document listing feature phase
+## Integration Pitfalls (Where Two Changes Interact Badly)
 
 ---
 
-### Pitfall 12: MinIO Presigned URL Expiry — Stale Links in the UI
+### Integration Pitfall A: Admin Rearchitecture + client.js Splitting — Wrong Order Causes Test Blindness
 
-**What goes wrong:**
-The document preview and download UI displays links generated as MinIO presigned URLs with a 1-hour expiry. The Vue frontend fetches the document list on page load, stores the URLs in Pinia state, and renders them as `<img src>` or `<a href>`. If the user leaves the tab open for 2 hours and then clicks a link, they get a 403 (presigned URL expired). No error is shown; the image just fails to load or the download silently fails.
+**Phases:** Admin panel rearchitecture + frontend refactoring
 
-**Why it happens:**
-Presigned URLs feel like permanent links. Teams generate them at list time for convenience and cache them in frontend state without expiry awareness.
+**What goes wrong:** If `client.js` is split into domain sub-files before the admin routes are moved to `/admin/*`, the new `api/admin.js` sub-file gets created. Components are then updated to point at the new route structure. But if the split happened first and components were simultaneously moved to import from `api/admin.js` directly (bypassing the barrel), the existing tests (which mock `client.js` imports) no longer cover the new import path. Tests pass, bugs hide.
 
-**How to avoid:**
-- Do not embed presigned URLs in list responses. Return only document metadata.
-- Generate presigned URLs **on demand**: a separate `GET /api/documents/{id}/download-url` endpoint generates a short-lived URL (5–15 minutes) at the moment of user intent.
-- Alternatively, proxy document bytes through the FastAPI backend (`GET /api/documents/{id}/file` streams from MinIO) — eliminates presigned URL complexity at the cost of bandwidth.
-- If presigned URLs are cached in frontend state, include the expiry timestamp and regenerate before expiry.
-
-**Warning signs:**
-- Presigned URLs included in document list response JSON
-- Frontend stores presigned URLs in Pinia state without TTL tracking
-- No `GET /api/documents/{id}/download-url` endpoint (or equivalent)
-- `presigned_url_expiry = 3600` with no frontend refresh logic
-
-**Phase to address:** DB + MinIO migration phase (Phase 2) and document access phase
+**Prevention:** Split `client.js` using the re-export barrel pattern first. Verify all existing tests still pass against the barrel. Then rearchitect admin routes. The barrel acts as a compatibility shim throughout both phases. Only remove the barrel after all tests are updated to import from sub-files.
 
 ---
 
-### Pitfall 13: OAuth Token for Cloud Storage — Revocation Not Handled
+### Integration Pitfall B: Virtual Scrolling + Drag-and-Drop Cannot Be Added Simultaneously
 
-**What goes wrong:**
-A user connects Google Drive via OAuth. The app stores the encrypted access token + refresh token. Six months later, the user revokes the app's access in their Google account settings. The next time DocuVault tries to access their Drive, it gets a 401. The refresh token exchange also fails with `invalid_grant`. The app has no handler for this — it retries, logs an error, and the user sees a generic "storage error" with no path to reconnect.
+**Phases:** Frontend performance + UX improvements
 
-**Why it happens:**
-OAuth happy-path is well-documented. Revocation and `invalid_grant` handling are in footnotes. Teams handle 401 → refresh → retry but don't handle refresh failure → user notification.
+**What goes wrong:** Virtual scroll and HTML5 drag-and-drop between rows both depend on the same DOM elements. Virtual scroll keeps only visible rows in the DOM. A user dragging a file toward a folder that is currently scrolled out of the virtual window will never trigger `dragover` on that folder row — it is not in the DOM. `StorageBrowser.vue`'s existing drag-into-folder implementation (lines 88-90) relies on `@dragover.prevent` on folder rows. In a virtual list, off-screen folder rows do not receive this event.
 
-**How to avoid:**
-- Wrap all cloud storage adapter calls in a two-level error handler:
-  - Level 1: 401 → attempt refresh → retry.
-  - Level 2: refresh fails with `invalid_grant` or `token_revoked` → mark connection as `REQUIRES_REAUTH` in DB, **do not retry**, surface a "reconnect required" notice to the user.
-- The `cloud_connections` table must have a `status` column: `ACTIVE | REQUIRES_REAUTH | ERROR`.
-- The UI must poll or react to `REQUIRES_REAUTH` state and prompt the user to re-authorize, not just show an error toast.
-- Never silently swallow a revoked-token error or retry indefinitely.
-
-**Warning signs:**
-- Cloud storage adapter raises generic `StorageError` for all OAuth errors without distinguishing revocation
-- No `status` or `needs_reauth` column on `cloud_connections`
-- Reconnect UI not planned in feature scope
-
-**Phase to address:** Cloud storage integration phase
+**Prevention:** Decide the list interaction model before implementing either feature. If virtual scrolling is added, redesign drag-to-folder: the sidebar folder tree (always fully rendered, outside the virtual list) becomes the drop target. This is a UX design decision that must be made before either feature is implemented, not a detail to resolve mid-phase.
 
 ---
 
-### Pitfall 14: Cloud Storage Rate Limits — No Backoff, No Per-User Throttling
+### Integration Pitfall C: Responsive Sidebar + Admin Guard Race on Mobile Page Load
 
-**What goes wrong:**
-Multiple users with Google Drive connected trigger simultaneous document uploads. The app hits Google's per-app rate limit (Drive API: 20,000 requests/100 seconds/user, but also global per-project limits). Google returns 429. The app has no retry-with-backoff; uploads fail and the errors are attributed to the individual user, not the platform-level limit.
+**Phases:** Responsive layout + admin panel rearchitecture
 
-**Why it happens:**
-Rate limits are per-API-key, not per-user. A single misbehaving user or burst of activity for all users shares the same quota. Teams only test with a single user.
+**What goes wrong:** The current `beforeEach` guard correctly awaits `authStore.refresh()` before checking `authStore.user?.role` (router lines 82-88). This is correct. The risk emerges when adding nested admin child routes: a developer adding a component-level `created()` or `onMounted()` auth check in an admin page component, trying to guard against unauthorized access "just in case." If that component check does not await the refresh (because the token is memory-only and gone on mobile page reload), `authStore.user` is null at that point, the component check redirects the user to `/login`, and the correct guard never gets to run. The result is that admins are bounced to login on every mobile page reload.
 
-**How to avoid:**
-- Implement exponential backoff with jitter for all cloud storage adapter calls (start 1s, max 32s, 3 retries).
-- Use a task queue (Celery or FastAPI BackgroundTasks with a semaphore) for cloud-destined uploads rather than processing inline in the request handler.
-- Log 429 responses separately from other errors — they indicate platform-level throttling, not user errors.
-- Per-provider rate limit documentation should be captured in adapter docstrings.
-
-**Warning signs:**
-- Cloud upload performed synchronously inside the HTTP request handler with no retry logic
-- No `tenacity` or equivalent retry decorator on provider calls
-- 429 responses from cloud APIs cause 500 responses to the end user
-
-**Phase to address:** Cloud storage integration phase
-
----
-
-### Pitfall 15: GDPR Right to Erasure — Cloud Copies Not Deleted
-
-**What goes wrong:**
-A user requests account deletion. The app deletes the PostgreSQL rows, the MinIO objects, and the user record. But if the user's documents were stored in Google Drive or OneDrive via the cloud storage adapter, those files remain on the cloud provider. The user's data has not actually been erased from all systems.
-
-**Why it happens:**
-Account deletion is implemented against the systems the team controls (PostgreSQL, MinIO). Cloud storage is treated as "the user's own storage" so deletion is skipped. Under GDPR, if the platform wrote files to the user's cloud storage on their behalf as a data processor, erasure obligations may extend there.
-
-**How to avoid:**
-- Account deletion must enumerate all `cloud_connections` for the user and call `adapter.delete_all_user_files()` (or equivalent) on each active connection.
-- If the cloud connection is already in `REQUIRES_REAUTH` state, the deletion cannot proceed automatically — log a compliance alert and require manual follow-up or notify the user to delete manually.
-- Document the data flow in a data map: "files stored in X go to Y" — this is a GDPR Article 30 requirement.
-- Right to erasure flow must be tested as part of acceptance criteria, not assumed to work.
-
-**Warning signs:**
-- Account deletion handler only operates on PostgreSQL and MinIO
-- No `delete_user_files` method in the `StorageBackend` interface
-- No GDPR data map in project documentation
-
-**Phase to address:** Cloud storage integration phase and account management phase
-
----
-
-### Pitfall 16: Encryption Key Management — Single Key for All Users
-
-**What goes wrong:**
-All cloud credentials are encrypted with one Fernet key stored in `CLOUD_ENCRYPTION_KEY` env var. If this key is exposed (leaked `.env`, compromised deployment config, insider threat), every user's cloud credentials decrypt at once. The privacy-first model collapses entirely.
-
-**Why it happens:**
-One key is simpler than per-user keys. Fernet key derivation per user is slightly more complex to implement.
-
-**How to avoid:**
-- Derive a per-user encryption key from the master key + a user-specific salt: `HKDF(master_key, salt=user_id_bytes, info=b"cloud-credentials")`. The salt is stored in the users table.
-- Even if the master key leaks, an attacker still needs each user's salt to decrypt their credentials.
-- Rotate the master key on a schedule: re-encrypt all stored credentials with the new key in a background job.
-- Audit log any code path that accesses the encryption key — this should only ever happen in the storage adapter, never in API handlers.
-- Never log the encryption key or derived key material, even at DEBUG level.
-
-**Warning signs:**
-- Single `ENCRYPTION_KEY` env var with no per-user derivation
-- Encryption/decryption called directly in API endpoint handlers (not in the adapter layer)
-- No key rotation plan documented
-
-**Phase to address:** Cloud storage integration phase (design the key derivation before writing the first line of credential storage code)
-
----
-
-### Pitfall 17: Shared Document — Quota Not Charged to Sharer Correctly After Revoke
-
-**What goes wrong:**
-User A shares a document with User B. The document is not duplicated — it stays in User A's storage and User A's quota. User A revokes the share. If the quota update on revoke has a bug (or is missing), User A's used bytes may drift from reality over time. At scale, quota inaccuracies accumulate and users can either be locked out prematurely or exceed limits invisibly.
-
-**Why it happens:**
-Sharing is implemented as a metadata-only operation (a `shares` table row), but quota accounting is only re-examined on upload and delete. Edge cases (revoke, owner deletion while share is active, cloud storage document quota) are skipped.
-
-**How to avoid:**
-- Quota is a property of documents, not shares. Ensure the quota model is: "sum of `file_size` for all documents where `owner_id = user_id`." Shares do not affect quota calculation.
-- Recalculate quota from source-of-truth (a `SUM` query) as a periodic background job and reconcile against the cached `used_bytes` value. Alert if drift exceeds 1%.
-- The `DELETE /documents/{id}` handler must atomically decrement quota and delete the DB row and MinIO object in a single transaction (DB) + best-effort cleanup (MinIO).
-
-**Warning signs:**
-- `used_bytes` stored as a counter updated by application code, never reconciled against a database SUM
-- Share revocation handler doesn't touch quota (correct if quota is owner-only, but must be verified)
-- Document deletion does not atomically update quota
-
-**Phase to address:** Quotas and sharing phases
-
----
-
-## Technical Debt Patterns
-
-| Shortcut | Immediate Benefit | Long-term Cost | When Acceptable |
-|----------|-------------------|----------------|-----------------|
-| Single global encryption key for cloud credentials | Simple env var config | Single point of failure; one leak decrypts all users | Never for a SaaS product |
-| localStorage JWT storage | Easy Axios integration | XSS → full account takeover, TOTP bypass | Never; httpOnly cookies have identical DX once set up |
-| Synchronous DB driver (psycopg2) with FastAPI | Familiar, simple | Event loop blocking under any load | Never for new greenfield code; acceptable only during an explicitly time-boxed spike |
-| Presigned URL in list response | One fewer endpoint | Stale URLs, user-facing failures after expiry | Only for short-lived signed URLs (<5 min) with TTL tracking in frontend |
-| Skip per-user key derivation | Fewer moving parts | Catastrophic blast radius on key leak | Never for cloud credential encryption |
-| Inline quota check (read-check-write) without atomic update | Simple code | Silent quota bypass under concurrent load | Never for enforced limits |
-| Soft-coding 8-char UUID prefix as document IDs (existing) | Shorter IDs | Collision risk at scale; insecure for auth tokens | Replace with full UUID before multi-user goes live |
-
----
-
-## Integration Gotchas
-
-| Integration | Common Mistake | Correct Approach |
-|-------------|----------------|------------------|
-| Google Drive OAuth | Storing `access_token` only; ignoring `refresh_token` | Store both; refresh_token is issued only on first authorization — store immediately or it's lost |
-| OneDrive / MSAL | Treating MSAL token cache as permanent | MSAL token cache can be invalidated by Microsoft; always handle `invalid_grant` and re-auth prompt |
-| Nextcloud | Using Basic Auth with plain credentials | Use App Passwords (Nextcloud-specific token), never store the user's Nextcloud master password |
-| MinIO | Using `minio.get_object()` for large files without streaming | Stream the response: `response.stream(32768)` or use boto3 streaming; loading full file to memory crashes on large PDFs |
-| MinIO | Treating bucket names as security boundaries | Bucket names are not credentials; isolation is enforced by object key prefix + IAM policy. Set MinIO IAM so the app's service account can only access the designated bucket |
-| PostgreSQL | Using `autocommit=True` for all connections | Quota updates and document record creation must be transactional; autocommit makes rollback impossible |
-| PyOTP (TOTP) | Using default `valid_window=0` then switching to `valid_window=2` for "user convenience" | Window=1 (±30s) tolerates clock skew. Window=2+ increases brute-force surface disproportionately |
-
----
-
-## Performance Traps
-
-| Trap | Symptoms | Prevention | When It Breaks |
-|------|----------|------------|----------------|
-| O(N) metadata scan on every document list (existing pattern) | List endpoint slows linearly with document count | Paginated SQL query with index on `(user_id, created_at)` | ~500 documents per user |
-| Topic count scan on every topic fetch (existing pattern) | `GET /topics` latency spikes as documents grow | Materialized counter column updated on insert/delete, or cached with 30s TTL | ~1,000 documents |
-| Synchronous MinIO upload inline in HTTP handler | Requests time out on large files; one upload blocks all other requests | Background task queue; return 202 Accepted with job ID | First user uploading a file >10 MB |
-| Eager loading all cloud connections on user login | Login latency grows with number of connected providers | Lazy-load cloud connection status; only check on storage page | >3 cloud providers per user |
-| Full-text search via `ILIKE '%term%'` on document content | Full table scan on every search | PostgreSQL `tsvector` full-text index on extracted text column | ~10,000 documents platform-wide |
-| JWT validation on every request without caching public key | Repeated public key fetch (if using asymmetric JWT) | Cache the signing key in memory; never refetch on every request | High request volume |
-
----
-
-## Security Mistakes
-
-| Mistake | Risk | Prevention |
-|---------|------|------------|
-| CORS `allow_origins=["*"]` retained from existing codebase | Cross-origin requests from attacker-controlled pages | Set exact origin (frontend URL) in production; never wildcard with credentials |
-| File type validation defined but not enforced (existing) | Executable or malicious file uploads | Enforce MIME type check at upload boundary; also validate magic bytes (not just Content-Type header) |
-| No file size limit at HTTP boundary (existing) | Memory exhaustion, DoS via large upload | Add `max_upload_bytes` limit in FastAPI middleware before reading body |
-| API keys in plaintext JSON (existing) | Credential leakage via Docker volume mount | Env vars for all secrets; never serialize keys to disk in application data directory |
-| Password reset without invalidating existing sessions | Attacker keeps session after victim resets password | Invalidate all sessions for user on successful password reset |
-| Audit log includes document metadata (filenames) | Filename can reveal document content | Audit log stores only document ID, event type, timestamp, IP — no filenames |
-| Admin can read `cloud_connections.encrypted_token` column | Ciphertext exposure; retroactive decryption if key leaks | Exclude credential columns from all admin serializers by policy |
-| No breach check on registration password | Users reuse passwords from breached services | Integrate HIBP k-anonymity API on registration |
-
----
-
-## UX Pitfalls
-
-| Pitfall | User Impact | Better Approach |
-|---------|-------------|-----------------|
-| Silent presigned URL expiry (image fails to load, download does nothing) | User thinks the app is broken; no recovery path | On-demand URL generation; show explicit "link expired, regenerating..." state |
-| TOTP enrollment without backup codes | User loses phone → permanently locked out of account | Issue 8–10 single-use backup codes at TOTP enrollment; require user to acknowledge |
-| Quota error shown only as "Upload failed" | User doesn't know why; may try repeatedly | Return structured quota error: `{"error": "quota_exceeded", "used": 98MB, "limit": 100MB}` |
-| Cloud storage reconnect required, but no in-app prompt | User's uploads silently fail until they notice the settings page | Banner notification or upload-time prompt: "Your Google Drive connection needs re-authorization" |
-| Folder delete with documents inside silently deletes documents | Data loss without confirmation | Require explicit confirmation listing document count; offer "move to root" alternative |
-| Share revoke with no notification to recipient | Recipient sees documents disappear without explanation | Audit-trail entry visible to recipient: "Access to [folder] was revoked by [owner]" |
-
----
-
-## "Looks Done But Isn't" Checklist
-
-- [ ] **TOTP enrollment:** Backup codes issued, stored hashed, and acknowledged by user before TOTP is marked active
-- [ ] **Password reset:** Does NOT create a full authenticated session — routes through login with TOTP check
-- [ ] **Document delete:** Atomically decrements quota AND removes MinIO object AND removes DB row in a single transaction
-- [ ] **Account delete:** Deletes from MinIO, PostgreSQL, AND calls `adapter.delete_user_files()` for each cloud connection
-- [ ] **Cloud disconnect:** Revokes OAuth token at provider (not just deletes local record) — provider refresh tokens remain valid until explicitly revoked
-- [ ] **Quota display:** Shows real-time usage, not cached value from registration — must query SUM from DB
-- [ ] **Sharing:** Shared documents do NOT copy to recipient's quota — verify with a `SELECT SUM(file_size) WHERE owner_id = recipient_id` before and after share
-- [ ] **Migration:** Document count in PostgreSQL equals document count in old JSON store before cutover flag is flipped
-- [ ] **Presigned URLs:** Never in list responses — verified by API contract test asserting no `url` field in list endpoint response body
-- [ ] **Admin isolation:** Admin token cannot retrieve document content — verified by dedicated negative-access test
-
----
-
-## Recovery Strategies
-
-| Pitfall | Recovery Cost | Recovery Steps |
-|---------|---------------|----------------|
-| JWT in localStorage discovered post-launch | HIGH | Rotate all tokens (force logout all users), redeploy with httpOnly cookies, communicate to users |
-| Quota race condition caused 10% of users to exceed quota | MEDIUM | Run `UPDATE quotas SET used_bytes = (SELECT SUM(file_size) FROM documents WHERE owner_id = user_id)` reconciliation; enforce atomic updates going forward |
-| Flat-file migration data loss (documents missing post-cutover) | HIGH | Restore from pre-migration backup of JSON data directory; re-run migration with dual-write; reconcile counts |
-| Encryption key leaked (single-key model) | CRITICAL | Immediately rotate key; re-encrypt all credentials with new key; notify affected users; assume all cloud credentials compromised — prompt all users to revoke and reconnect |
-| Admin escalation (admin accessed user documents) | HIGH | Audit log review to determine scope; GDPR breach notification if EU users affected (72h window); patch authorization layer; force session invalidation |
-| Cloud connection revoked but app retried indefinitely | LOW | Mark all stuck connections as `REQUIRES_REAUTH`; send user notification; add `invalid_grant` handler to adapter |
-
----
-
-## Pitfall-to-Phase Mapping
-
-| Pitfall | Prevention Phase | Verification |
-|---------|------------------|--------------|
-| JWT in localStorage | Phase 1 — Auth | Confirm no `localStorage.setItem('token', ...)` in frontend; auth cookie is httpOnly in browser DevTools |
-| TOTP bypass via password reset | Phase 1 — Auth | Integration test: reset password → assert no full session created → assert login still requires TOTP |
-| Refresh token reuse detection | Phase 1 — Auth | Test: use a rotated (old) refresh token → assert 401 and full family revocation |
-| TOTP timing attack / brute force | Phase 1 — Auth | Rate limit test: 6th TOTP attempt within window → assert 429 |
-| Path traversal in MinIO keys | Phase 2 — DB + MinIO migration | Unit test: filename with `../` → assert stored key is UUID-based, not user-provided |
-| Quota race condition | Phase 2 — DB + MinIO migration | Concurrent upload test: 2 threads uploading to full quota → assert only one succeeds |
-| Admin privilege escalation | Phase 1 + every phase adding resource endpoints | Negative access test: admin JWT → `GET /documents/{other_user_doc_id}` → assert 403 |
-| Cloud credential leakage via admin query | Phase 3 — Cloud storage | Test: admin list user cloud connections → assert response contains no `token` or `encrypted_` fields |
-| Flat-file to PostgreSQL data loss | Phase 2 — DB + MinIO migration | Count reconciliation: `assert json_doc_count == db_doc_count` in migration script |
-| Blocking I/O in async handlers | Phase 2 — DB + MinIO migration | Load test with 10 concurrent requests; assert no event loop warnings; check SQLAlchemy driver is asyncpg |
-| N+1 queries on document list | Phase 2 — DB + MinIO migration | Enable SQLAlchemy echo; assert document list query count = 1 regardless of result size |
-| Presigned URL expiry | Phase 2 — DB + MinIO migration | API contract test: list endpoint response contains no presigned URL fields |
-| OAuth revocation not handled | Phase 3 — Cloud storage | Mock `invalid_grant` from OAuth provider → assert connection status set to `REQUIRES_REAUTH`, not retried |
-| Rate limits without backoff | Phase 3 — Cloud storage | Mock 429 from provider → assert exponential backoff, not immediate 500 to user |
-| GDPR right to erasure incomplete | Phase 3 — Cloud storage + account mgmt | Account deletion test: assert cloud adapter `delete_user_files` called for each active connection |
-| Single encryption key | Phase 3 — Cloud storage | Code review gate: assert per-user HKDF derivation; no single-key decryption in any code path |
-| Quota drift from sharing/revoke | Sharing phase | Reconciliation query: `SUM(file_size WHERE owner_id = user)` vs `used_bytes` — assert < 1% drift |
-
----
-
-## Sources
-
-- Project context: `/Users/nik/Documents/Progamming/document_scanner/.planning/PROJECT.md`
-- Codebase audit: `/Users/nik/Documents/Progamming/document_scanner/.planning/codebase/CONCERNS.md`
-- Auth pitfalls: OWASP JWT Security Cheat Sheet, OWASP Authentication Cheat Sheet (well-established, HIGH confidence)
-- OAuth token lifecycle: RFC 6749 Section 10.4 (refresh token revocation), Google OAuth error codes documentation (HIGH confidence from training data)
-- MinIO/S3 path traversal: AWS S3 object key documentation; known class of vulnerability in multi-tenant S3-prefix isolation (HIGH confidence)
-- Quota race conditions: Classic check-then-act concurrency pattern; PostgreSQL SELECT FOR UPDATE documentation (HIGH confidence)
-- GDPR Article 17 (right to erasure) and Article 30 (records of processing): well-established regulatory requirements (HIGH confidence)
-- N+1 query pattern: SQLAlchemy documentation on relationship loading strategies (HIGH confidence)
-- TOTP RFC 6238; PyOTP library behavior from training data (MEDIUM — verify PyOTP `valid_window` defaults against current docs before implementation)
-
----
-
-*Pitfalls research for: DocuVault — multi-user SaaS document management (FastAPI + Vue 3 + PostgreSQL + MinIO)*
-*Researched: 2026-05-21*
+**Prevention:** The single `beforeEach` guard is the only place that should call `refresh()` or check roles. Page components must not independently re-check auth. If a component needs the current user, it reads from `authStore.user` — which is guaranteed to be populated by the time the component mounts, because the guard has already awaited the refresh.