Architecture Decision Records¶
Architecture Decision Records (ADRs) are lightweight documents that capture significant architectural decisions made during the development of the Revel backend. Each record describes the context that motivated the decision, the decision itself, and its consequences.
We use the MADR (Markdown Any Decision Records) format.
Template¶
When adding a new ADR, use this template:
# ADR-NNNN: Title
## Status
Accepted | Proposed | Deprecated | Superseded by [ADR-XXXX]
## Context
What is the issue motivating this decision?
## Decision
What is the change we're proposing or doing?
## Consequences
What becomes easier or harder because of this change?
Index¶
| ADR | Title | Status |
|---|---|---|
| ADR-0000 | Synchronous ORM Over Django Async ORM | Accepted |
| ADR-0001 | HMAC-Signed URLs with Caddy Instead of S3/MinIO | Accepted |
| ADR-0002 | Hybrid Service Architecture (Functions + Classes) | Accepted |
| ADR-0003 | Django Ninja Over Django REST Framework | Accepted |
| ADR-0004 | No Dependency Injection Container | Accepted |
| ADR-0005 | Django 5.2 LTS Policy | Accepted |
| ADR-0006 | Compiled Translation Files (.mo) in Git | Superseded by ADR-0011 |
| ADR-0007 | Let Celery Exceptions Propagate | Accepted |
| ADR-0008 | Environment-Based Feature Flags | Accepted (FEATURE_GOOGLE_SSO superseded by ADR-0016) |
| ADR-0009 | Referral Payout Bounded Contexts | Accepted |
| ADR-0010 | Dependency License & Vulnerability Checks | Accepted |
| ADR-0011 | Build Compiled Translations (.mo), Don't Commit Them | Accepted |
| ADR-0012 | Hybrid OFFLINE/ONLINE Membership Subscriptions | Accepted |
| ADR-0013 | Stripe Connect Direct Charges for Subscriptions | Accepted |
| ADR-0014 | Terminal Subscription States with Bounded Revival | Accepted |
| ADR-0015 | Reactive Dunning + simple-history Audit for Subscriptions | Accepted |
| ADR-0016 | Generic OIDC login, hand-rolled on PyJWT + httpx | Accepted |
| ADR-0017 | Platform listings via a provider protocol | Accepted |
| ADR-0018 | OAuth 2.1 / OIDC provider on django-oauth-toolkit | Accepted |
Adding a New ADR¶
- Determine the next sequential number (e.g.,
0008). - Create a new file:
docs/adr/NNNN-short-slug.md. - Use the template above.
- Set the status to Proposed until the team reviews it, then update to Accepted.
- Add an entry to the index table in this file.
When to Write an ADR
Write an ADR when a decision is significant and hard to reverse: choosing a framework, changing a core pattern, adopting a new tool, or deprecating an existing approach. Day-to-day implementation choices do not need ADRs.