curo1305andClaude Sonnet 4.6
123ae5b29b
Moves phases 08–11 execution artifacts from .planning/phases/ to .planning/milestones/v0.2-phases/ to keep .planning/phases/ clean for the next milestone. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
7.1 KiB
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.jsfunction (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"