docs(01-02): complete database schema and driver storage plan
- 01-02-SUMMARY.md: TDD execution results, decisions, self-check passed - STATE.md: progress updated (100% phase 1), 3 decisions recorded - ROADMAP.md: phase 1 marked Complete (3/3 summaries)
This commit is contained in:
@@ -0,0 +1,139 @@
|
||||
---
|
||||
phase: 01-foundation
|
||||
plan: "02"
|
||||
subsystem: database
|
||||
tags: [peewee, sqlite, wal, orm, content-addressed-storage, sha256]
|
||||
|
||||
# Dependency graph
|
||||
requires:
|
||||
- phase: 01-01
|
||||
provides: "FastAPI app shell with lifespan, config.py with DATA_DIR/DB_PATH/DRIVERS_DIR"
|
||||
provides:
|
||||
- "Peewee SqliteDatabase instance with WAL mode + foreign_keys pragma (imptune/db/database.py)"
|
||||
- "Full ORM schema: Client, Driver, Printer, Icon models for phases 1-5 (imptune/db/models.py)"
|
||||
- "SHA256 content-addressed DriverStore with deduplication (imptune/storage/driver_store.py)"
|
||||
- "Auto-initializing database via FastAPI lifespan startup"
|
||||
affects:
|
||||
- phase-02-clients
|
||||
- phase-03-drivers
|
||||
- phase-04-printers
|
||||
- phase-05-export
|
||||
|
||||
# Tech tracking
|
||||
tech-stack:
|
||||
added: [peewee==3.17.9]
|
||||
patterns:
|
||||
- "Deferred SqliteDatabase init (db.init() at runtime so tests can override DB_PATH)"
|
||||
- "safe=True on create_tables() for idempotent schema creation"
|
||||
- "SHA256 content-addressed file storage for deduplication"
|
||||
|
||||
key-files:
|
||||
created:
|
||||
- imptune/db/__init__.py
|
||||
- imptune/db/database.py
|
||||
- imptune/db/models.py
|
||||
- imptune/storage/__init__.py
|
||||
- imptune/storage/driver_store.py
|
||||
- tests/test_db.py
|
||||
modified:
|
||||
- imptune/main.py
|
||||
|
||||
key-decisions:
|
||||
- "Deferred SqliteDatabase pattern (SqliteDatabase(None)) so tests can patch imptune.config.DB_PATH without module reload"
|
||||
- "Full schema created upfront in phase 1 per locked user decision — later phases only add routes/logic, no schema changes"
|
||||
- "init_db() placed in lifespan (not @app.on_event) consistent with 01-01 decision — plan text was outdated"
|
||||
|
||||
patterns-established:
|
||||
- "TDD: RED (failing tests) then GREEN (implementation) for all db/storage modules"
|
||||
- "ORM: All models extend BaseModel which references shared db instance via Meta.database = db"
|
||||
- "Storage: DriverStore encapsulates all filesystem operations for driver packages"
|
||||
|
||||
requirements-completed: [INFRA-01, INFRA-02]
|
||||
|
||||
# Metrics
|
||||
duration: 3min
|
||||
completed: 2026-04-10
|
||||
---
|
||||
|
||||
# Phase 1 Plan 2: Database Schema and Driver Storage Summary
|
||||
|
||||
**Peewee ORM with deferred SQLiteDatabase, full 4-table schema (Client/Driver/Printer/Icon) for all phases, and SHA256-deduplicating DriverStore — wired into FastAPI lifespan**
|
||||
|
||||
## Performance
|
||||
|
||||
- **Duration:** ~3 min
|
||||
- **Started:** 2026-04-10T09:29:54Z
|
||||
- **Completed:** 2026-04-10T09:32:07Z
|
||||
- **Tasks:** 2 (Task 1 with TDD + Task 2)
|
||||
- **Files modified:** 7
|
||||
|
||||
## Accomplishments
|
||||
|
||||
- Full Peewee ORM schema with 4 tables covering all phases 1-5 (locked-in upfront design decision)
|
||||
- WAL journal mode and foreign_keys pragma enforced via init_db() on every startup
|
||||
- Deferred database pattern allows tests to safely redirect DB_PATH to tmp dirs without module reloads
|
||||
- DriverStore provides SHA256 content-addressed storage with automatic deduplication on write
|
||||
- init_db() integrated into FastAPI lifespan — database auto-creates at DATA_DIR/imptune.db on startup
|
||||
|
||||
## Task Commits
|
||||
|
||||
Each task was committed atomically:
|
||||
|
||||
1. **Task 1: Peewee models, database init, and driver storage** - `dea4148` (feat — TDD GREEN)
|
||||
2. **Task 2: Wire database init into FastAPI startup** - `88d9c5f` (feat)
|
||||
|
||||
**Plan metadata:** (docs commit follows)
|
||||
|
||||
_Note: TDD — tests written first (RED), then implementation (GREEN). No separate refactor pass needed._
|
||||
|
||||
## Files Created/Modified
|
||||
|
||||
- `imptune/db/__init__.py` - Package marker
|
||||
- `imptune/db/database.py` - Deferred SqliteDatabase instance + init_db() with WAL/FK pragmas
|
||||
- `imptune/db/models.py` - BaseModel, Client, Driver, Printer, Icon ORM models
|
||||
- `imptune/storage/__init__.py` - Package marker
|
||||
- `imptune/storage/driver_store.py` - SHA256 content-addressed DriverStore class
|
||||
- `tests/test_db.py` - 7 TDD tests (table creation, WAL, FK, idempotency, save, dedup, get_path)
|
||||
- `imptune/main.py` - Added import and call to init_db() in lifespan
|
||||
|
||||
## Decisions Made
|
||||
|
||||
- **Deferred database pattern**: Used `SqliteDatabase(None)` + `db.init()` at runtime so pytest's `monkeypatch` on `imptune.config.DB_PATH` works without module reload side effects.
|
||||
- **Lifespan over @app.on_event**: Plan text referenced `@app.on_event("startup")` but 01-01 established the lifespan pattern. Followed existing code — no deviation registered as this was alignment with an existing decision.
|
||||
- **Full schema upfront**: All 4 tables created in phase 1 per user's locked decision, so phases 2-5 only add application logic.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] Installed missing peewee package**
|
||||
- **Found during:** Task 1 setup
|
||||
- **Issue:** peewee was in requirements.txt but not installed in the active Python environment
|
||||
- **Fix:** Ran `python -m pip install peewee==3.17.*`
|
||||
- **Files modified:** None (environment only)
|
||||
- **Verification:** `import peewee` succeeds, all 7 tests pass
|
||||
- **Committed in:** Not committed (environment dependency install)
|
||||
|
||||
---
|
||||
|
||||
**Total deviations:** 1 auto-fixed (1 blocking — missing dependency)
|
||||
**Impact on plan:** No scope creep. peewee install was a prerequisite, not new scope.
|
||||
|
||||
## Issues Encountered
|
||||
|
||||
- Plan Task 2 referenced `@app.on_event("startup")` but the existing `main.py` from plan 01-01 already uses `asynccontextmanager lifespan` (per a decision recorded in STATE.md). Added `init_db()` to the lifespan function instead — no regression.
|
||||
|
||||
## User Setup Required
|
||||
|
||||
None - no external service configuration required.
|
||||
|
||||
## Next Phase Readiness
|
||||
|
||||
- Database layer complete — all ORM models importable and tested
|
||||
- `init_db()` wired in — first app startup creates the database automatically in DATA_DIR
|
||||
- DriverStore ready for driver upload routes (phase 3)
|
||||
- All 24 tests pass (7 new + 17 existing), zero regressions
|
||||
|
||||
---
|
||||
*Phase: 01-foundation*
|
||||
*Completed: 2026-04-10*
|
||||
Reference in New Issue
Block a user