Architecture Decision Records

This directory is the code-native home for BetterFleet-wide architecture decision records. Product-specific ADRs should live in the relevant product repository, but cross-product decisions belong here.

Working Rule

• Before changing shared architecture, platform conventions, API standards, persistence strategy, observability, delivery conventions, or cross-service patterns, review the relevant ADRs here.
• If a change intentionally conflicts with an accepted ADR, update or supersede the ADR in the same change rather than silently drifting from it.
• Create and maintain BetterFleet-wide ADRs in this repo.

ADRs

ADR	Status	Date
0001 - Record architecture decisions	Accepted	2022-05-26
0002 - Cognito for Authentication and Authorisation	Accepted	2022-05-27
0003 - AWS Amplify for Authentication	Accepted	2022-05-27
0004 - DynamoDB for default database	Superseded by 0005 - Data Persistence	2022-06-17
0005 - Data Persistence	Accepted	2022-09-21
0006 - Trunk-Based Development	Accepted	2022-11-17
0007 - Generalised principle for automation	Accepted	2022-11-18
0008 - Naming Repositories, Services, and URLs	Accepted	2022-11-24
0009 - Use Timezone Aware DateTimes and UTC	Accepted	2022-12-20
0010 - Use semantic release	Accepted	2023-01-10
0011 - Centralized feature flag repository	Accepted	2023-02-15
0012 - Use Named Exports in Storybook	Accepted	2023-02-21
0013 - RESTful TITLE GraphQL	Accepted	2023-05-22
0014 - Service Granularity	Proposed	2023-05-22
0015 - Async/co-routine exception handling pattern	Proposed	2024-01-10
0016 - Logging & log levels	Proposed	2024-01-16
0017 - Instantiated Models	Proposed	2024-02-07
0018 - Repository Pattern for Database Access	Accepted	2024-05-16
0019 - Use of Design Tokens in TypeScript React Application	<Proposed \| Accepted \| Rejected \| Deprecated \| Superseded by x>	13/06/2024
0020 - API backwards compatibility and versioning	Proposed	2025-01-24
0021 - Alembic Migration strategy	Unknown	Unknown
0022 - Consistent react-hook-form usage	Unknown	Unknown
0023 - Domain Event-Driven Architecture	Proposed	2025-09-01
0024 - Domain Event Bus Tech Stack	Proposed	2025-09-02
0025 - No enum types in DB table columns	Accepted	2025-10-30
0026 - In-Memory Ormar Stores for Repository testing	Proposed	2024-11-13
0027 - Storing Tab State in Query and Local Storage	Proposed	2025-11-24
0028 - Adopt OpenTelemetry Semantic Conventions for Structured Logging	Proposed	Unknown
0029 - Adopt RFC 9457 for HTTP Error Responses	Proposed	Unknown
0030 - Use GitLab registry and Terraform state for ECS services	Accepted	2026-04-29
0031 - Adopt DDD, Hexagonal Architecture, and CQRS for Python Domain Services	Proposed	2026-05-11

Notes

• 0019 still carries a placeholder status line.
• 0021 and 0022 do not currently expose explicit Date or Status headings.
• 0028 and 0029 do not currently expose explicit Date headings.
• 0004 remains marked as superseded so the decision history stays intact.

Guidance

Architecture Decision Records (ADRs) are a way to record decisions that we make in our architecture. An architectural decision can simply be viewed as decisions that may be expensive to change later.

This list of ADRs are ones that apply across all our products. Individual repositories should their own list, stored in the repository, that is specific to that product. adr-tools can be used to create and manage these, both for the handbook and individual projects.

We’re using the Decision record template from Michael Nygard.

When and how to record an ADR

As above, any time an decision could be expensive to change later, it's good to get a clear understanding for that. It could be around the use of a specific pattern, or 3rd party library, database, etc.

If the decision has already been made with consensus (making sure relevant people have had a say), it just needs to be documented as Accepted. If it's a decision that should get input from more people, create it as Proposed, and circulate to the team to add comments to the page. When the decision has been suitable shaped and ratified, set it to Accepted.

Sometimes, a decision will supersede another decision. In that case, update the status of the superseded ADR to "Superseded by x", with a document link to the superseding ADR.

Also, set the page icon accordingly, to quickly convey status in the side menu: ❓= Proposed ✅ = Accepted ❌ = Rejected, Deprecated, Superseded