> For the complete documentation index, see [llms.txt](https://docs.opendatadiscovery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opendatadiscovery.org/developer-guides/architecture-decision-log.md). # Architectural Decision Log 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)](/developer-guides/architecture-decision-log/adr-0001-openapi-generated-controller-interfaces.md) * [ADR-0002 — Centralised path-matcher authorization (no @PreAuthorize)](/developer-guides/architecture-decision-log/adr-0002-centralised-path-matcher-authorization.md) * [ADR-0004 — GenAI ships disabled by default and is a thin proxy](/developer-guides/architecture-decision-log/adr-0004-genai-disabled-by-default.md) * [ADR-0007 — Uniform reactive controller pipeline (Mono\, centralised error translation)](/developer-guides/architecture-decision-log/adr-0007-uniform-reactive-controller-pipeline.md) * [ADR-0008 — OpenAPI tags scope the generated API interfaces](/developer-guides/architecture-decision-log/adr-0008-openapi-tag-per-resource-scoping.md) * [ADR-0012 — Attachment storage backend is selected at boot](/developer-guides/architecture-decision-log/adr-0012-attachment-storage-backend-boot-selection.md) * [ADR-0018 — Outbound-integration config is fail-fast at boot](/developer-guides/architecture-decision-log/adr-0018-fail-fast-outbound-config-at-boot.md) * [ADR-0019 — Data Collaboration ships disabled by default](/developer-guides/architecture-decision-log/adr-0019-data-collaboration-disabled-by-default.md) * [ADR-0020 — Outbound Slack delivery is decoupled via a Postgres queue](/developer-guides/architecture-decision-log/adr-0020-decoupled-outbound-slack-delivery.md) * [ADR-0040 — Notifications ship disabled by default behind one condition](/developer-guides/architecture-decision-log/adr-0040-notifications-disabled-by-default.md) * [ADR-0041 — Notification channels activate by the presence of their keys](/developer-guides/architecture-decision-log/adr-0041-notification-per-channel-presence-activation.md) * [ADR-0042 — Notification fan-out is fail-soft per channel](/developer-guides/architecture-decision-log/adr-0042-notification-fail-soft-fan-out.md) * [ADR-0043 — The notification WAL consumer is a leader-elected singleton](/developer-guides/architecture-decision-log/adr-0043-notification-wal-single-leader.md) * [ADR-0044 — Postgres replication artefacts are lazy-created, never dropped](/developer-guides/architecture-decision-log/adr-0044-postgres-artefact-lazy-create-no-drop.md) * [ADR-0021 — Activity streams use cursor pagination, not offset/limit](/developer-guides/architecture-decision-log/adr-0021-activity-stream-cursor-pagination.md) * [ADR-0022 — Activity view-modes are a single enum parameter, not separate endpoints](/developer-guides/architecture-decision-log/adr-0022-activity-view-modes-single-parameter.md) * [ADR-0028 — High-volume tables are range-partitioned ahead of need, at boot and nightly](/developer-guides/architecture-decision-log/adr-0028-range-partition-lifecycle.md) * [ADR-0045 — Housekeeping is a separate subsystem from partition management](/developer-guides/architecture-decision-log/adr-0045-housekeeping-partition-separation.md) * [ADR-0046 — Housekeeping ships enabled by default (opt-out)](/developer-guides/architecture-decision-log/adr-0046-housekeeping-opt-out-by-default.md) * [ADR-0073 — ODDRN is the universal identity for every entity](/developer-guides/architecture-decision-log/adr-0073-oddrn-universal-identity.md) * [ADR-0071 — PostgreSQL is the only required runtime dependency](/developer-guides/architecture-decision-log/adr-0071-postgres-only-runtime-dependency.md) * [ADR-0070 — Ingestion is one wire contract shared by pull and push producers](/developer-guides/architecture-decision-log/adr-0070-pull-push-ingestion-contract.md) * [ADR-0072 — The platform is a contract-first, reactive, two-language stack](/developer-guides/architecture-decision-log/adr-0072-contract-first-reactive-stack.md) * [ADR-0003 — The catalog is read-collaborative — only mutations are permission-gated](/developer-guides/architecture-decision-log/adr-0003-read-collaborative-authorization.md) * [ADR-0058 — Deletion is soft — DELETED is a status, not a row removal](/developer-guides/architecture-decision-log/adr-0058-soft-delete-deletion-model.md) * [ADR-0074 — Authentication is a pluggable mode selected by auth.type, defaulting to DISABLED](/developer-guides/architecture-decision-log/adr-0074-pluggable-auth-modes.md) * [ADR-0075 — Heavyweight features ship off by default; operational-hygiene jobs ship on](/developer-guides/architecture-decision-log/adr-0075-feature-gating-posture.md) * [ADR-0076 — In-context concept help is an information icon in a hover tooltip](/developer-guides/architecture-decision-log/adr-0076-inline-info-tooltip-affordance.md) * [ADR-0078 — Editing a consequential field uses a change-preview confirmation that reduces into the store](/developer-guides/architecture-decision-log/adr-0078-confirm-and-store-reduce-field-edits.md) * [ADR-0079 — Ingestion authentication is one gate over /ingestion/\*\*, not per-route filters](/developer-guides/architecture-decision-log/adr-0079-ingestion-authentication-filter-coverage.md) ## 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](/developer-guides/how-to-contribute.md) to propose or correct one.