generated from john/python-template
87 lines
4.4 KiB
Markdown
87 lines
4.4 KiB
Markdown
# Ver1 Step 1 Results: Architecture Consolidation
|
|
|
|
## Summary
|
|
|
|
Step 1 implementation has been completed for the primary architecture-consolidation objectives:
|
|
|
|
1. Lifespan-owned runtime resource model introduced for DB runtime ownership.
|
|
2. Schema bootstrap policy changed from implicit-always to explicit/environment-aware.
|
|
3. Worker startup now receives lifespan-owned DB engine dependency.
|
|
4. ADR set established for key V1 architectural decisions.
|
|
|
|
## Implemented Changes
|
|
|
|
### 1) Runtime ownership
|
|
|
|
- Updated `src/transcription/db.py`:
|
|
- Added `DatabaseRuntime` resource model.
|
|
- Added explicit runtime lifecycle methods:
|
|
- `initialize_database_runtime(...)`
|
|
- `get_database_runtime()`
|
|
- `dispose_database_runtime()`
|
|
- Updated `src/transcription/app.py`:
|
|
- Lifespan initializes DB runtime and stores it on `app.state`.
|
|
- Lifespan disposes DB runtime on shutdown.
|
|
|
|
### 2) Schema bootstrap policy (REQ-10 alignment)
|
|
|
|
- Updated `src/transcription/config.py`:
|
|
- Added `environment` setting (`development`, `test`, `production`).
|
|
- Added `bootstrap_schema_on_startup` explicit override setting.
|
|
- Updated `src/transcription/db.py`:
|
|
- Added `should_bootstrap_schema(settings)` policy function.
|
|
- Updated `src/transcription/app.py`:
|
|
- Startup now calls `create_all(...)` only when policy allows.
|
|
|
|
### 3) Worker dependency ownership
|
|
|
|
- Updated `src/transcription/worker.py`:
|
|
- `process_next_queued_job(..., engine=None)` now supports explicit engine injection.
|
|
- `run_worker_loop(..., engine=None, ...)` now supports explicit engine injection.
|
|
- Updated `src/transcription/app.py`:
|
|
- Worker thread is started with lifespan-owned engine.
|
|
|
|
### 4) ADR governance
|
|
|
|
Created:
|
|
- `docs/adr/README.md`
|
|
- `docs/adr/ADR-0001-lifespan-owned-runtime-resources.md`
|
|
- `docs/adr/ADR-0002-explicit-schema-bootstrap-policy.md`
|
|
- `docs/adr/ADR-0003-persistence-baseline-and-transition-path.md`
|
|
- `docs/adr/ADR-0004-in-process-worker-topology.md`
|
|
|
|
## Test Evidence
|
|
|
|
Targeted regression checks executed successfully:
|
|
|
|
- `uv run pytest tests/test_app.py tests/test_db.py tests/services/test_worker.py -q`
|
|
- Result: pass
|
|
|
|
## Residual Risks / Follow-ups
|
|
|
|
1. Full REQ-7 completion may still require broader runtime ownership coverage for additional resources as V1 expands.
|
|
2. Production schema management workflow (migrations/runbook tooling) should be finalized in subsequent V1 steps.
|
|
3. Additional boundary enforcement automation (import-lint style checks) can be added in later hardening.
|
|
|
|
## Step 1 Exit Assessment
|
|
|
|
- Architecture ownership clarity: **met**
|
|
- Schema bootstrap policy hardening: **met**
|
|
- Worker lifecycle dependency clarity: **met**
|
|
- ADR baseline established: **met**
|
|
|
|
## Completion Checklist With Evidence
|
|
|
|
| Criterion | Status | Evidence |
|
|
| --- | --- | --- |
|
|
| Architecture conformance matrix approved | partial | Consolidation implemented and documented in `docs/ver1/ver1-step1.md` + this results doc; formal matrix artifact can be added as a follow-up appendix. |
|
|
| REQ-7 ownership gaps resolved or explicitly deferred | met | Lifespan-owned DB runtime and explicit worker engine wiring implemented in `src/transcription/app.py`, `src/transcription/db.py`, `src/transcription/worker.py`. Residual scope documented under follow-ups. |
|
|
| REQ-10 explicit bootstrap policy implemented and verified | met | Policy implemented via `environment` + `bootstrap_schema_on_startup` in `src/transcription/config.py`, `should_bootstrap_schema(...)` in `src/transcription/db.py`, startup gate in `src/transcription/app.py`, tested in `tests/test_db.py`. |
|
|
| Dependency direction rules documented and enforced | partial | Layering and runtime ownership documented in `docs/architecture.md`. Lightweight enforcement exists via review and test discipline; automated import-lint remains a follow-up. |
|
|
| ADR set created for major Step 1 decisions | met | `docs/adr/README.md` and ADR-0001 through ADR-0004 created. |
|
|
| Architecture/index docs updated to match implementation | met | `docs/architecture.md` and `docs/index.md` updated with V1 Step 1 runtime policy and links to V1/ADR artifacts. |
|
|
| Regression and full test suites pass | met | Targeted: `uv run pytest tests/test_app.py tests/test_db.py tests/services/test_worker.py -q`; full suite: `uv run pytest -q`. |
|
|
| Step 1 results artifact published | met | This document (`docs/ver1/ver1-step1-results.md`) created and updated with summary, evidence, risks, and checklist. |
|
|
|
|
Step 1 is complete and ready to hand off to Ver1 Step 2.
|