Architecture Decision Records
This section documents all Architecture Decision Records (ADRs) for the OpenTabletop project, following the MADR 4.0.0 format. ADRs are numbered sequentially (never reused or reordered) but grouped by domain below for discoverability.
Governance & Process
Decisions about how the project operates: format standards, licensing, versioning, contribution workflows, and documentation tooling.
| ADR | Title | Status |
|---|---|---|
| ADR-0001 | Use MADR 4.0.0 for Architecture Decision Records | Accepted |
| ADR-0003 | Dual Licensing – Apache 2.0 for Code, CC-BY-4.0 for Spec | Accepted |
| ADR-0004 | RFC-Based Governance with Steering Committee Transition | Accepted |
| ADR-0005 | Semantic Versioning for Spec and Implementations | Accepted |
| ADR-0030 | Structured Data Contributions via Issue Templates | Accepted |
| ADR-0031 | RFC Changes Require Reference Implementation | Superseded by ADR-0045 |
| ADR-0033 | mdbook with Mermaid for Documentation | Accepted |
| ADR-0045 | Specification-Only Repository | Accepted |
Core Data Model
The foundational entity model: game entity design, relationships, taxonomy, player count polls, playtime modeling, editions, and classification criteria.
| ADR | Title | Status |
|---|---|---|
| ADR-0006 | Unified Game Entity with Type Discriminator | Accepted |
| ADR-0007 | Combinatorial Expansion Property Model | Accepted |
| ADR-0008 | UUIDv7 Primary Keys with URL Slugs and BGG Cross-References | Accepted |
| ADR-0009 | Controlled Vocabulary for Taxonomy | Accepted |
| ADR-0010 | Structured Per-Player-Count Polling Data | Accepted |
| ADR-0011 | Typed Game Relationships with JSONB Metadata | Accepted |
| ADR-0014 | Dual Playtime Model – Publisher-Stated and Community-Reported | Accepted |
| ADR-0034 | Experience-Bucketed Playtime Adjustment | Proposed |
| ADR-0035 | Edition-Level Property Deltas | Accepted |
| ADR-0037 | Formal Entity Type Classification Criteria | Proposed |
| ADR-0043 | Player Count Sentiment Model Improvements | Proposed |
| ADR-0044 | Player Entity and Collection Data | Proposed |
| ADR-0045 | Specification-Only Repository | Accepted |
API Design
Protocol, pagination, filtering, error handling, resource embedding, hypermedia, caching, and bulk export.
| ADR | Title | Status |
|---|---|---|
| ADR-0002 | Use REST with OpenAPI 3.2 as the API Protocol | Accepted |
| ADR-0012 | Keyset (Cursor-Based) Pagination | Accepted |
| ADR-0013 | Compound Multi-Dimensional Filtering as Core Feature | Accepted |
| ADR-0015 | RFC 9457 Problem Details for Error Responses | Accepted |
| ADR-0016 | API Key Authentication with Tiered Rate Limits | Accepted |
| ADR-0017 | Selective Resource Embedding via ?include Parameter | Accepted |
| ADR-0018 | HAL-Style Hypermedia Links for Discoverability | Accepted |
| ADR-0019 | Bulk Data Export Endpoints | Accepted |
| ADR-0028 | Cache-Control Headers and ETags | Accepted |
Infrastructure & Implementation Guidance
Cloud-native design, deployment, observability, search, database migrations, and legacy system migration. These ADRs document recommended patterns for operators building conforming servers – they are guidance, not requirements of the standard. ADR-0025 (reference server) and ADR-0026 (SDK generation) are superseded by ADR-0045.
| ADR | Title | Status |
|---|---|---|
| ADR-0020 | Twelve-Factor Application Design | Accepted |
| ADR-0021 | Distroless Container Images | Accepted |
| ADR-0022 | Kubernetes-Native Deployment with Docker Compose Fallback | Accepted |
| ADR-0023 | OpenTelemetry for Unified Observability | Accepted |
| ADR-0024 | Immutable Infrastructure with Blue-Green Deployment | Accepted |
| ADR-0025 | Rust with Axum and SQLx for the Reference Server | Superseded by ADR-0045 |
| ADR-0026 | OpenAPI Generator for SDK Generation | Superseded by ADR-0045 |
| ADR-0027 | PostgreSQL Full-Text Search | Accepted |
| ADR-0029 | Versioned Plain SQL Migration Files | Accepted |
| ADR-0032 | Strangler Fig Pattern for BGG Legacy Migration | Accepted |
Data Model Extensions
Extensions to the core model for BGG parity, publisher/designer utility, and analytical capabilities.
| ADR | Title | Status |
|---|---|---|
| ADR-0036 | Time-Series Snapshots and Trend Analysis | Proposed |
| ADR-0038 | Alternate Names and Localization Support | Proposed |
| ADR-0039 | Extended Game Credits with Role Taxonomy | Proposed |
| ADR-0040 | Edition Product and Physical Metadata | Proposed |
| ADR-0041 | Community Signals and Aggregate Statistics | Proposed |
| ADR-0042 | Game Awards and Recognition | Proposed |
Chronological Index
All ADRs in sequential order for reference. Numbers are append-only and never reused.
| ADR | Title | Status |
|---|---|---|
| ADR-0001 | Use MADR 4.0.0 for Architecture Decision Records | Accepted |
| ADR-0002 | Use REST with OpenAPI 3.2 as the API Protocol | Accepted |
| ADR-0003 | Dual Licensing – Apache 2.0 for Code, CC-BY-4.0 for Spec | Accepted |
| ADR-0004 | RFC-Based Governance with Steering Committee Transition | Accepted |
| ADR-0005 | Semantic Versioning for Spec and Implementations | Accepted |
| ADR-0006 | Unified Game Entity with Type Discriminator | Accepted |
| ADR-0007 | Combinatorial Expansion Property Model | Accepted |
| ADR-0008 | UUIDv7 Primary Keys with URL Slugs and BGG Cross-References | Accepted |
| ADR-0009 | Controlled Vocabulary for Taxonomy | Accepted |
| ADR-0010 | Structured Per-Player-Count Polling Data | Accepted |
| ADR-0011 | Typed Game Relationships with JSONB Metadata | Accepted |
| ADR-0012 | Keyset (Cursor-Based) Pagination | Accepted |
| ADR-0013 | Compound Multi-Dimensional Filtering as Core Feature | Accepted |
| ADR-0014 | Dual Playtime Model – Publisher-Stated and Community-Reported | Accepted |
| ADR-0015 | RFC 9457 Problem Details for Error Responses | Accepted |
| ADR-0016 | API Key Authentication with Tiered Rate Limits | Accepted |
| ADR-0017 | Selective Resource Embedding via ?include Parameter | Accepted |
| ADR-0018 | HAL-Style Hypermedia Links for Discoverability | Accepted |
| ADR-0019 | Bulk Data Export Endpoints | Accepted |
| ADR-0020 | Twelve-Factor Application Design | Accepted |
| ADR-0021 | Distroless Container Images | Accepted |
| ADR-0022 | Kubernetes-Native Deployment with Docker Compose Fallback | Accepted |
| ADR-0023 | OpenTelemetry for Unified Observability | Accepted |
| ADR-0024 | Immutable Infrastructure with Blue-Green Deployment | Accepted |
| ADR-0025 | Rust with Axum and SQLx for the Reference Server | Superseded by ADR-0045 |
| ADR-0026 | OpenAPI Generator for SDK Generation | Superseded by ADR-0045 |
| ADR-0027 | PostgreSQL Full-Text Search | Accepted |
| ADR-0028 | Cache-Control Headers and ETags | Accepted |
| ADR-0029 | Versioned Plain SQL Migration Files | Accepted |
| ADR-0030 | Structured Data Contributions via Issue Templates | Accepted |
| ADR-0031 | RFC Changes Require Reference Implementation | Superseded by ADR-0045 |
| ADR-0032 | Strangler Fig Pattern for BGG Legacy Migration | Accepted |
| ADR-0033 | mdbook with Mermaid for Documentation | Accepted |
| ADR-0034 | Experience-Bucketed Playtime Adjustment | Proposed |
| ADR-0035 | Edition-Level Property Deltas | Accepted |
| ADR-0036 | Time-Series Snapshots and Trend Analysis | Proposed |
| ADR-0037 | Formal Entity Type Classification Criteria | Proposed |
| ADR-0038 | Alternate Names and Localization Support | Proposed |
| ADR-0039 | Extended Game Credits with Role Taxonomy | Proposed |
| ADR-0040 | Edition Product and Physical Metadata | Proposed |
| ADR-0041 | Community Signals and Aggregate Statistics | Proposed |
| ADR-0042 | Game Awards and Recognition | Proposed |
| ADR-0043 | Player Count Sentiment Model Improvements | Proposed |
| ADR-0044 | Player Entity and Collection Data | Proposed |
| ADR-0045 | Specification-Only Repository | Accepted |