Architectural Decision Log

Architecture Decision Records for ODD Platform — the significant decisions the codebase embodies, reconstructed from the source with the code evidence to verify each one.

This log records the architecture decisions ODD Platform embodies — the deliberate, structural choices a contributor needs to understand why the platform is built the way it is. Each record is reconstructed from the source code and cites the file:line evidence behind it, so you can verify every claim against the repository.

These are descriptive, not prescriptive: they document decisions the code already makes, rather than decreeing new ones. Each record carries a Status, the Context that motivated the decision, the Decision itself, its Consequences (trade-offs and what it enables or precludes), and the Evidence in the codebase.

Records

• ADR-0001 — Contract-first HTTP layer (OpenAPI-generated controller interfaces)

• ADR-0002 — Centralised path-matcher authorization (no @PreAuthorize)

• ADR-0004 — GenAI ships disabled by default and is a thin proxy

• ADR-0007 — Uniform reactive controller pipeline (Mono<ResponseEntity>, centralised error translation)

• ADR-0008 — OpenAPI tags scope the generated API interfaces

• ADR-0012 — Attachment storage backend is selected at boot

• ADR-0018 — Outbound-integration config is fail-fast at boot

• ADR-0019 — Data Collaboration ships disabled by default

• ADR-0020 — Outbound Slack delivery is decoupled via a Postgres queue

• ADR-0040 — Notifications ship disabled by default behind one condition

• ADR-0041 — Notification channels activate by the presence of their keys

• ADR-0042 — Notification fan-out is fail-soft per channel

• ADR-0043 — The notification WAL consumer is a leader-elected singleton

• ADR-0044 — Postgres replication artefacts are lazy-created, never dropped

• ADR-0021 — Activity streams use cursor pagination, not offset/limit

• ADR-0022 — Activity view-modes are a single enum parameter, not separate endpoints

• ADR-0028 — High-volume tables are range-partitioned ahead of need, at boot and nightly

• ADR-0045 — Housekeeping is a separate subsystem from partition management

• ADR-0046 — Housekeeping ships enabled by default (opt-out)

• ADR-0073 — ODDRN is the universal identity for every entity

• ADR-0071 — PostgreSQL is the only required runtime dependency

• ADR-0070 — Ingestion is one wire contract shared by pull and push producers

• ADR-0072 — The platform is a contract-first, reactive, two-language stack

• ADR-0003 — The catalog is read-collaborative — only mutations are permission-gated

• ADR-0058 — Deletion is soft — DELETED is a status, not a row removal

• ADR-0074 — Authentication is a pluggable mode selected by auth.type, defaulting to DISABLED

• ADR-0075 — Heavyweight features ship off by default; operational-hygiene jobs ship on

How to read a record

• Status — accepted (the decision is live in the code), superseded (replaced by a later ADR), or deprecated.

• Evidence — every record points at the source that embodies the decision; if the code changes, the record should change with it.

• New decisions are added here as they are reconstructed and reviewed; see How to contribute to propose or correct one.