Architecture Decision Records

Design decisions that are not obvious from reading the code. Each ADR documents why a decision was made, not just what. The code already shows the what.

ADRs come in two layers:

• Implementation decisions (numbered 001-008): runtime, data model and operational choices discovered while building PROTEA. They explain trade-offs of concrete code paths (KNN algorithm choice, queue topology, deduplication strategy, retries, etc.).

• Strategic decisions (D1-D31): plan-level decisions taken in the master plan revision 3 (2026-05-05). They drive the structure of the project, the deployment story, and the thesis writing cadence.

Implementation decisions

All implementation ADRs (001-008) follow the MADR template (Status / Context / Decision / Consequences sections). They are numbered in discovery order, not superseded by the D-series, and remain the authoritative record for the runtime, data model, and operational choices described.

ADR	Status	Decision	Problem it solves
001	Accepted	KNN on CPU, not pgvector or GPU	pgvector does not scale to 500K+ vectors; GPU must be reserved for inference
002	Accepted	Two-session worker pattern	A mid-operation crash left the job invisible to monitoring
003	Accepted	Two types of consumer	Thousands of batch jobs per pipeline flooded the jobs table
004	Accepted	Dead letter queue and retries	Failed messages were lost; retries without backoff amplified failures
005	Accepted	Reusable RabbitMQ connections	A coordinator dispatching 500 batches opened 500 TCP connections
006	Accepted	Sequence deduplication by MD5	30K duplicate sequences in Swiss-Prot waste hours of GPU time
007	Accepted	Contract-first integration with protea-reranker-lab	Re-ranker iteration cadence would contaminate the production dependency tree
008	Accepted	PK coverage fix in cafaeval fork	Upstream cafaeval reports coverage > 1 in PK; precision is under-divided
009	Accepted	Pre-dispatch cancellation nack in QueueConsumer	Cancelled messages held a prefetch slot and could deadlock the predictions queue

Strategic decisions

Decisions taken in the master plan revision 3 (2026-05-05). Statuses: Accepted, Pending (gate opens at the indicated phase), Deferred (scheduled later in the timeline) or Obsolete (superseded by a later revision).

ID	Decision	Status	Phase / Gate
D1	Project structure (7 code repos)	Accepted	F0 (closed); enacted F0-F2
D2	export_research_dataset in protea-core	Accepted	F1
D3	GOPrediction.features as JSONB	Accepted	F3
D4	API versioning	Pending	gate at F4
D5	Front-end in protea-core	Accepted	F1
D6	Authentication strategy	Pending	gate at F5
D7	Observability stack	Pending	gate at F-OPS
D8	UI component library	Accepted	F8a
D9	OBSOLETE: lab as runtime dependency	Obsolete	superseded by D1
D10	schema_sha_v2 migration	Pending	T1.6 (requires_human)
D11	Job narrative model	Accepted	F3
D12	F-EXP as QA reproduction	Accepted	F-EXP
D13	Early UI track parallel to F2	Accepted	F8a / F8b
D14	Plugin granularity (deferred)	Deferred	F9 post-defense
D15	protea-method shipping channels	Accepted	F-OPS
D16	Thesis repository location	Accepted	F0
D17	OBSOLETE: thesis template choice	Obsolete	n/a
D18	Thesis writing model	Accepted	F-THESIS
D19	F-RESEARCH targets	Accepted	F-RESEARCH
D20	Co-supervisor review cadence	Accepted	F-THESIS
D21	Thesis writing parallel from F0	Accepted	F-THESIS
D22	Thesis as research diary	Accepted	F-THESIS
D23	LAFA submission strategy	Accepted	F-LAFA
D24	Hardcoded params externalisation (T-CONF)	Accepted	F0 (closed)
D25	HPC operation mode	Pending	gate at F-OPS
D26	Container runtime: OCI plus Apptainer	Accepted	F-OPS
D27	Image registry	Pending	gate at F-OPS
D28	Secrets management	Pending	gate at F-OPS
D29	Release pipeline	Pending	gate at F-OPS
D30	Insights appendix	Accepted	F7
D31	T2B.5 Method Object reframe (sub-cluster granularity)	Accepted	F2C / §24
D34	Selective rerank resurrection, recompute not archaeology	Accepted	F-EXP-RESET
D35	Canonical 8-PLM embedding config IDs	Accepted	F-EXP-RESET
D36	PLM axis explicit in dataset naming	Accepted	F-EXP-RESET
D37	Single auth system, manual approvals, multi-instance (FEAT-AUTH)	Accepted	F-AUTH (complete, FARM-AUTH.1-11)
D38	Defer neural-head champion; pivot to curated dataset packaging (F-DATA-PACK)	Accepted	F-DATA-PACK