Decision Log

Decision Log

Durable architectural decisions live as ADRs under docs/adr/. This page is their summary.

No	Decision	Summary rationale	Status	Month
0001	Two-service architecture (Python + Java)	"Who is allowed to do what" on the JVM, "how to reason" on Python. Splitting later would be a painful refactor.	✅	1
0002	Single datastore: PostgreSQL + pgvector	Knowing one database deeply is worth more than knowing three superficially. Keeps the component count low.	✅	1
0003	Flyway owns the schema	The schema lives in the repo as versioned SQL; a single source of truth for both services.	✅	1

Pending decisions

Topic	When it will be decided
Queue technology (DB-based, or Redis/RabbitMQ)	Start of Month 4
Eval set file format (JSONL schema)	Start of Month 3
Metrics stack (Prometheus + Grafana, or an alternative)	Start of Month 5
LLM provider abstraction (single vs multi-provider)	Mid Month 2

When to write an ADR

"Six months from now, will we ask why we did it this way?"

If the answer is yes, write an ADR. Writing an ADR takes 20 minutes; the cost of a forgotten decision runs into days.

Also: the interview "defense note" you'll write in Month 6 is built from these ADRs. Each ADR is a ready answer to "why did you choose this architecture?" in an interview.