Bootwitch Doctor — Architecture
README · ARCHITECTURE · TECHNICAL
The architecture changed twice during the experiment: first in our understanding of the repository, then in the implementation itself. The agents shared one set of maps so every lane could see which connections were proven, incomplete, or still missing.
Before repair
The starting application had two paths that looked successful but ended in different process-local repositories.
import file -> import command -> private memory repository -> printed note
browser -> HTTP API -> service -> server memory repository -> restart -> empty
The importer could print a note, and the API could return one. Neither outcome proved that the note reached durable application state.
The orchestration layer
Five agent lanes worked around one integration boundary:
architecture + integration lead
/ | | \
/ | | \
SQLite storage atomic runtime independent
owner import composition verifier
\ | | /
\ | | /
shared contracts and traces
|
integrated application
The lanes were parallel where ownership did not overlap. Connections became serial acceptance gates when one implementation depended on another.
| Gate | What had to be true |
|---|---|
| Storage gate | SQLite matched the repository contract and survived close/reopen. |
| Runtime gate | The server constructed that adapter once and closed it on shutdown or startup failure. |
| Restart gate | A separate server process could read earlier committed data. |
| Import gate | The service validated the whole payload before one batch write. |
| Failure gate | A controlled later-row failure rolled the entire batch back. |
Repaired application path
JSON file
-> real import command
-> one POST /api/import
-> complete-payload validation
-> NoteService.import_notes
-> repository.add_many
-> one SQLite transaction
-> configured database file
-> complete server restart
-> same notes through GET /api/notes
The browser and import command now reach the same HTTP service and SQLite database. The in-memory repository remains useful as a fast test adapter, but the application does not select it at runtime.
Why the traces ran both ways
The forward trace answered where a request would go. The backward trace started with a claim such as “the imported note survives restart” and identified every dependency required for that claim to be true.
Running both traces caught a subtle class of false confidence: a green component beside a red connection. The component evidence was real, but it proved a narrower claim than the application needed.
State and failure boundaries
NoteServiceowns validation and normalization rules.- The repository contract separates application behavior from storage.
SQLiteNoteRepositoryowns schema checks, transactions, and database reads.- Runtime composition creates one repository and injects that same instance into the service.
- The server owns shutdown and bind-failure cleanup.
- Batch import validates first, then publishes inside one transaction.
- Unexpected storage failures reach the server error boundary rather than being mislabeled as invalid user input.
What comes next
The tested import/restart path is complete: one batch reaches SQLite and remains available to a new server process. Browser-level acceptance testing is the next boundary; broader export and client-state ideas remain outside this repair snapshot.