> 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) ## 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.opendatadiscovery.org/developer-guides/architecture-decision-log.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.