# Phase 8: Stack Upgrade & Backend Decomposition — Discussion Log

> **Audit trail only.** Do not use as input to planning, research, or execution agents.
> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.

**Date:** 2026-06-07
**Phase:** 8-Stack-Upgrade-Backend-Decomposition
**Areas discussed:** documents.py split structure, auth.py split structure, Phase 7.1 deferred gap, Vite 5→6 migration scope, client.js domain grouping, Phase 7.1 toast implementation, Backend dep bumps, CODE-08 shared.py scope

---

## documents.py split structure

| Option | Description | Selected |
|--------|-------------|----------|
| Merge search with CRUD → 3 files | upload.py, proxy.py, documents.py (list+search merged) | |
| Keep 4 files as described | 4 sub-modules matching ROADMAP's functional areas | ✓ |

**User's choice:** Keep 4 files as described

| Option | Description | Selected |
|--------|-------------|----------|
| Into CRUD / documents.py | Re-classify operates on a single document by ID | |
| Into upload.py | Re-triggers the Celery pipeline, adjacent to confirm | |
| You decide | Researcher/planner places it based on code | ✓ |

**User's choice:** Researcher decides re-classify placement

| Option | Description | Selected |
|--------|-------------|----------|
| upload.py, proxy.py, crud.py, listing.py | Explicit names for 4 areas | |
| upload.py, content.py, documents.py, search.py | Alternative naming | |
| You decide | Researcher picks names based on actual code | ✓ |

**User's choice:** Researcher picks file names

---

## auth.py split structure

| Option | Description | Selected |
|--------|-------------|----------|
| Keep 4 files, JTI/ES256/fgp fold into tokens.py | All token-security concerns together | |
| Keep 4 files as originally described | JTI/ES256/fgp placed by researcher | |
| You decide | Researcher reads actual code and picks cleanest split | ✓ |

**User's choice:** Researcher decides auth split

| Option | Description | Selected |
|--------|-------------|----------|
| Independent — router split is about HTTP grouping | api/auth/ groups by HTTP endpoint families | |
| Aligned — mirror services structure in API split | Module names match services/auth.py logical groupings | ✓ |

**User's choice:** api/auth/ sub-module names mirror services/auth.py logical groupings

---

## Phase 7.1 deferred gap

| Option | Description | Selected |
|--------|-------------|----------|
| Intentionally deferred — keep it separate | Phase 8 proceeds as pure decomposition/upgrade | |
| Include in Phase 8 | Phase 8 absorbs the 2 Phase 7.1 plans before decomposition | ✓ |

**User's choice:** Include Phase 7.1 in Phase 8

| Option | Description | Selected |
|--------|-------------|----------|
| First wave — do 7.1 before the refactor | 7.1 completes first, then decomposition follows | ✓ |
| Separate plan within Phase 8 | 7.1 as a dedicated plan that can run independently | |

**User's choice:** Phase 7.1 as Wave 1, decomposition follows

---

## Vite 5→6 migration scope

| Option | Description | Selected |
|--------|-------------|----------|
| Assume it just works — bump and verify | Bump, run dev+build, fix anything that breaks | |
| Research first — there may be config changes | Check Vite 6 migration guide against existing vite.config.js | ✓ |

**User's choice:** Research migration guide against vite.config.js before bumping

| Option | Description | Selected |
|--------|-------------|----------|
| All install-only for now | No integration in Phase 8 | |
| @tailwindcss/forms needs tailwind.config.js wiring | Must register plugin even without styles | |
| You decide | Researcher determines which need config wiring | ✓ |

**User's choice:** Researcher determines PERF-01 package integration requirements

---

## client.js domain grouping

| Option | Description | Selected |
|--------|-------------|----------|
| Most specific domain file only | Every function in exactly one file, no duplication | |
| You decide | Researcher maps all 35+ consumer imports | ✓ |

**User's choice:** Researcher maps imports and picks grouping

| Option | Description | Selected |
|--------|-------------|----------|
| In client.js alongside request() | Both transport helpers in same file | |
| New api/utils.js | fetchWithRetry in a separate utility module | ✓ |

**User's choice:** fetchWithRetry → new `frontend/src/api/utils.js`

---

## Phase 7.1 toast implementation

| Option | Description | Selected |
|--------|-------------|----------|
| Simple local implementation | Local reactive message + v-if in the two components | |
| Stub the global store early | Create empty useToastStore now; Phase 10 fills it in | ✓ |
| Skip the toast for now | Backend + tests only; toast waits for Phase 10 | |

**User's choice:** Create `useToastStore` stub in Phase 7.1; Phase 10 implements it

**Notes:** The stub establishes the `show()` API contract that Phase 10 must honor.

---

## Backend dep bumps

| Option | Description | Selected |
|--------|-------------|----------|
| Include backend bumps in Phase 8 | Bump FastAPI, SQLAlchemy, PyJWT + pip-audit | |
| Backend deps out of scope | PERF-01 is frontend-only; backend version management is separate | ✓ |

**User's choice:** Backend dep bumps out of scope for Phase 8

| Option | Description | Selected |
|--------|-------------|----------|
| Pin to exact versions | Convert >= to == for reproducible builds | ✓ |
| Leave floating for now | Only fix if bumping is in scope | |

**User's choice:** Pin current versions to == (no version changes, just reproducibility)

---

## CODE-08 shared.py scope

| Option | Description | Selected |
|--------|-------------|----------|
| Cross-package models → top-level api/schemas.py | New backend/api/schemas.py for models used by 2+ packages | ✓ |
| Duplicate across packages OK for now | Independent definition in each package's shared.py | |
| You decide | Researcher identifies actual cross-package overlap | |

**User's choice:** New `backend/api/schemas.py` for cross-package models; per-package `shared.py` for intra-package sharing

| Option | Description | Selected |
|--------|-------------|----------|
| Move any router-defined validators to services/ during split | Enforce CLAUDE.md rule during the split | ✓ |
| Split only — no validator migrations | Structural changes only | |

**User's choice:** Router-defined validators migrated to services/ during the split

---

## Claude's Discretion

- Exact file names for `api/documents/` sub-modules
- Exact file names for `api/auth/` sub-modules
- Re-classify endpoint placement within `api/documents/`
- Which validators in router files qualify for migration to `services/`
- Domain grouping of each `client.js` function (full import site mapping needed)
- Which PERF-01 packages require config wiring vs install-only

## Deferred Ideas

- Backend package version bumps (FastAPI to 0.136+, SQLAlchemy, PyJWT) — future phase
- Composition API migration for Vue components — explicitly out of scope for all v0.2 phases
- Virtual scrolling, dark mode, folder reordering, multi-select batch ops — already in REQUIREMENTS.md "Future"