curo/kite
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(08): capture phase context

Browse Source
This commit is contained in:
curo1305
2026-06-07 10:39:32 +02:00
parent 258b0006d6
commit 28e1e4aaf4
2 changed files with 310 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.planning/phases/08-stack-upgrade-backend-decomposition/08-DISCUSSION-LOG.md
+177
View File
@@ -0,0 +1,177 @@
# 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"