15 KiB
Architectural Decision Records (ADRs) Index
This directory holds StarPunk's Architectural Decision Records. Each ADR records one decision: its context, what was decided, and the consequences. Superseded ADRs are kept as history; their Status line names the ADR that replaced them.
Total ADR files: 69 (68 numbers: ADR-001 to ADR-044 and ADR-050 to ADR-073, with two files numbered ADR-012). See Numbering.
Status values: Accepted (in force), Superseded (replaced by a later ADR), Deprecated (withdrawn, nothing replaces it; none at present), Proposed (not implemented). "Accepted*" means accepted, with later changes noted in the ADR's Status section.
Current decisions by area
Foundation and process
| ADR | Title | Status | Summary |
|---|---|---|---|
| 001 | Python Web Framework Selection | Accepted | Flask as the web framework. |
| 002 | Flask Extensions and Dependencies | Accepted | A minimal dependency set; avoid Flask extensions where the standard library will do. |
| 003 | Front-end Technology Stack | Accepted | Server-rendered Jinja2 templates with minimal client-side code. |
| 006 | Python Virtual Environment Management with uv | Accepted | uv manages the virtual environment and dependencies. |
| 008 | Versioning Strategy | Accepted | Semantic Versioning, PEP 440 compatible. |
| 009 | Git Branching Strategy | Accepted | Simplified trunk-based development with feature branches and release tags. |
| 012 | Flaky Test Removal and Test Quality Standards | Accepted | Remove the multiprocessing migration tests and fix brittle assertions (done in v1.5.0). |
| 015 | Phase 5 Implementation Approach | Accepted | Version jump 0.5.1 → 0.6.0 for Phase 5 (historical). |
| 051 | Phase 1 Test Strategy and Implementation Review | Accepted | Review of the v1.1.1 Phase 1 test approach (historical). |
Storage and database
| ADR | Title | Status | Summary |
|---|---|---|---|
| 004 | File-Based Note Storage Architecture | Accepted | Note content in Markdown files under data/notes/YYYY/MM/, metadata in SQLite. |
| 013 | Expose deleted_at Field in Note Model | Accepted | deleted_at on the Note dataclass for soft deletes. |
| 020 | Automatic Database Migration System | Accepted | Numbered SQL migrations applied at startup and tracked in a table. |
| 031 | Database Migration System Redesign | Accepted | Baseline schema first, then migrations, so existing databases upgrade (implemented via ADR-032/033). |
| 032 | Initial Schema SQL Implementation for Migration System | Accepted | INITIAL_SCHEMA_SQL holds the baseline schema. |
| 033 | Database Migration System Redesign | Accepted | Frozen baseline schema; every later change only in migration files (v1.1.0). |
| 037 | Database Migration Race Condition Resolution | Accepted | SQLite BEGIN IMMEDIATE lock with retries so several gunicorn workers don't migrate at once. |
| 041 | Database Migration Conflict Resolution | Accepted | Handling a production database that fell into a migration edge case. |
See also database architecture.
Notes, slugs, media and search
| ADR | Title | Status | Summary |
|---|---|---|---|
| 062 | Timestamp-Based Slug Format | Accepted | Default slugs are YYYYMMDDHHMMSS timestamps (v1.5.0); replaces ADR-007. |
| 035 | Custom Slugs in Micropub | Accepted* | Honour mp-slug, sanitized, with reserved names protected (v1.1.0). |
| 034 | Full-Text Search with SQLite FTS5 | Accepted | FTS5 search over note content (v1.1.0). |
| 057 | Media Attachment Model | Accepted | Social-media-style image attachments: up to 4 per note, ordered, with captions. |
| 058 | Image Optimization Strategy | Accepted | Upload limits, automatic resizing and size variants. |
Feeds
| ADR | Title | Status | Summary |
|---|---|---|---|
| 014 | RSS Feed Implementation Strategy | Accepted* | RSS 2.0 feed; its WebSub deferral is superseded by ADR-071. |
| 038 | Multiple Syndication Format Support | Accepted | RSS, Atom and JSON Feed side by side (v1.1.2). |
| 071 | WebSub publishing with a built-in hub | Accepted | Built-in WebSub hub at /websub for StarPunk's own feeds (v2.10.0, amended v2.10.1). |
| 059 | Full Feed Media Standardization (Option 3) | Proposed | Full Media RSS, podcasts, video and thumbnails in feeds; not scheduled. |
IndieWeb: microformats, Webmention, Micropub
| ADR | Title | Status | Summary |
|---|---|---|---|
| 040 | Strict Microformats2 Compliance | Accepted | Full h-entry, h-card and h-feed markup (v1.3.0, reviewed v2.8.0). |
| 061 | Author Profile Discovery from IndieAuth | Accepted | The author h-card is read from ADMIN_ME and cached. |
| 063 | Webmention Implementation | Accepted | Async receiving (202) and sending via a background worker, SSRF guard, rate limits, moderation (v1.6.0, revised up to v2.10.1). Reconstructed. |
| 028 | Micropub Implementation Strategy | Accepted* | /micropub endpoint for creating posts (v1.0.0-rc.1); tokens now per ADR-064. |
| 039 | Micropub URL Construction Fix | Accepted | Fix the double slash in returned post URLs. |
| 067 | Micropub update, delete, drafts and replies | Accepted | Micropub update, delete, drafts and replies (v2.4.0). |
| 068 | Likes and reposts | Accepted* | like-of and repost-of posts (v2.5.0); bookmarks were added later in v2.9.0. |
See also IndieWeb protocols.
Crossposting (POSSE)
| ADR | Title | Status | Summary |
|---|---|---|---|
| 065 | Direct Syndication (POSSE) to GoToSocial | Accepted | Crosspost to GoToSocial/Mastodon-API servers from a background worker (v2.1.0). |
| 066 | Crossposting to Bluesky | Accepted | Bluesky as a second crosspost target (v2.2.0). |
| 069 | Crossposting to Threads | Accepted | Threads as a third target, with automatic token refresh (v2.6.0). |
| 070 | Links and link cards in crossposts | Accepted | Keep note links in crossposts and build link cards for the linked page (v2.6.3). |
| 073 | Backfeed of responses to crossposts | Proposed | Poll GoToSocial, Bluesky and Threads for responses to crossposts and store them as webmentions; admin backfill (planned v2.13.0). |
Authentication (current)
| ADR | Title | Status | Summary |
|---|---|---|---|
| 064 | OIDC Admin Login and Built-in IndieAuth Server | Accepted | Admin login via OIDC; StarPunk issues and verifies Micropub tokens itself (v2.0.0). |
| 010 | Authentication Module Design | Accepted* | Single auth.py module and server-side sessions; the login flow is now ADR-064. |
| 011 | Development Authentication Mechanism | Accepted | DEV_MODE login bypass for local development only. |
| 022 | Fix IndieAuth Callback Route Mismatch | Accepted | Auth routes live under /auth (v0.9.2). |
Operations, errors and monitoring
| ADR | Title | Status | Summary |
|---|---|---|---|
| 012 | HTTP Error Handling Policy | Accepted | Correct HTTP status codes (e.g. 404 for missing notes) across routes. |
| 052 | Configuration System Architecture | Accepted | Environment variables with defaults, loaded in one module. |
| 054 | Structured Logging Architecture | Accepted | Rotating log files with correlation IDs (v1.1.1). |
| 055 | Error Handling Philosophy | Accepted | Layered handling: graceful degradation, clear user messages, detailed logs. |
| 072 | Remove the metrics dashboard | Accepted | Drop the in-memory metrics system and dashboard; keep /health, /admin/health and logs (v2.12.0). |
See also deployment.
Superseded decisions
Kept for history. Most concern the IndieLogin.com and external-IndieAuth designs of v0.x–v1.6.0, all replaced by ADR-064 in v2.0.0.
| ADR | Title | Status | Summary |
|---|---|---|---|
| 005 | IndieLogin Authentication Integration | Superseded by 064 | Admin login through indielogin.com. |
| 007 | Slug Generation Algorithm | Superseded by 062 | Slugs from the first words of the note. |
| 053 | Performance Monitoring Strategy | Superseded by 072 | Built-in, standard-library performance metrics (v1.1.1). |
| 060 | Route Adapter for the Metrics Dashboard | Superseded by 072 | Adapt monitoring data to the dashboard template in the route (v1.1.1-rc.2). Reconstructed. |
| 016 | IndieAuth Client Discovery Mechanism | Superseded by 019 | h-app markup for client discovery. |
| 017 | OAuth Client ID Metadata Document Implementation | Superseded by 019 | OAuth client metadata endpoint. |
| 018 | IndieAuth Detailed Logging Strategy | Superseded by 064 | Redacted HTTP logging of the IndieAuth login flow. |
| 019 | IndieAuth Correct Implementation Based on IndieLogin.com API | Superseded by 025 | Draft of the IndieLogin.com PKCE flow. |
| 021 | IndieAuth Provider Strategy | Superseded by 064 | Keep IndieLogin.com for admin login. |
| 023 | IndieAuth Client Identification Strategy | Superseded by 064 | Visible h-app in the footer. |
| 024 | Static HTML Identity Pages for IndieAuth | Superseded by 064 | Standalone identity page pointing at indieauth.com. |
| 025 | IndieAuth Correct Implementation Based on IndieLogin.com API | Superseded by 064 | IndieLogin.com authentication with PKCE. |
| 026 | IndieAuth Token Exchange Compliance | Superseded by 064 | Token exchange parameters for the IndieAuth login. |
| 027 | IndieAuth Authentication Endpoint Correction | Superseded by 064 | Use the authentication (not token) endpoint for login. |
| 029 | Micropub IndieAuth Integration Strategy | Superseded by 050, 064 | Built-in token endpoint for Micropub (v1.0.0-rc.1). |
| 030 | External Token Verification Architecture | Superseded by 043, 064 | Verify Micropub tokens at a configured external endpoint. |
| 036 | IndieAuth Token Verification Method Diagnosis | Superseded by 064 | How to call the external token endpoint. |
| 042 | Versioning Strategy for Authorization Server Removal | Accepted (historical) | Remove the authorization server in 1.0.0-rc.4 rather than in a later release. |
| 043 | IndieAuth Endpoint Discovery Architecture | Superseded by 064 | Discover the token endpoint from ADMIN_ME to verify tokens. |
| 044 | IndieAuth Endpoint Discovery Implementation Details | Superseded by 064 | Implementation details of ADR-043. |
| 050 | Remove Custom IndieAuth Server | Superseded by 064 | Remove the built-in authorization and token server (done in v1.0.0-rc.4). |
| 056 | Use External IndieAuth Provider (Never Self-Host) | Superseded by 064 | Never run an IndieAuth server in StarPunk. |
ADR-042 is listed here because it only matters together with ADR-050; it was carried out and is not itself superseded.
Numbering
- Gap ADR-045 to ADR-049: never used; no document or code refers to them.
- Two ADR-012 files:
ADR-012-http-error-handling-policy.mdandADR-012-flaky-test-removal.md(added 2025-12-16). Both are cited as plain "ADR-012":starpunk/routes/admin.pyand early CHANGELOG entries mean the error policy,tests/test_migration_race_condition.pymeans the flaky-test one. Not renumbered, since other documents link to them. - Old numbers in headings: several files were renumbered without updating their first heading: ADR-037 and ADR-038 say "ADR-022", ADR-040 says "ADR-023", ADR-042 says "ADR-027", ADR-044 says "ADR-031". Older CHANGELOG entries use those old numbers ("ADR-022: Migration Race Condition Fix" is ADR-037; "ADR-031: IndieAuth Endpoint Discovery" is ADR-044). The file name is authoritative.
- ADR-060 was deleted in the v1.1.1-rc.2 review and reconstructed on 2026-11-03 because code still cites it. ADR-059 also mentions a planned "Option 2 (ADR-060)" for Media RSS that was never written.
- ADR-063 was lost with the uncommitted v1.6.0 docs and reconstructed on 2026-11-03.
- ADR-064 used twice: v1.6.0 code (
starpunk/rate_limiter.py,starpunk/routes/webmention.py) cites a lost "ADR-064: Webmention Rate Limiting"; the number was reused in v2.0.0 for OIDC login. The rate-limit decision is recorded in ADR-063, Decision 10.
How to create a new ADR
-
Use the next number after the highest existing one (currently ADR-074).
-
Name it
ADR-NNN-brief-descriptive-title.md. -
Follow the format of recent ADRs (e.g. ADR-070, ADR-071):
# ADR-NNN: Title ## Status Accepted (vX.Y.Z, YYYY-MM-DD) ## Context ## Decision ## Consequences ## Alternatives considered -
When a decision replaces an earlier one, change the earlier ADR's Status to "Superseded by ADR-NNN" with a one-line note; don't rewrite its body.
-
Add the ADR to this index.
Related documentation
- ../architecture/ — current system design
- ../design/ — per-version implementation designs
- ../standards/ — coding and documentation standards
- ../../CHANGELOG.md — what changed in each release
Last Updated: 2026-11-03 Total ADR files: 67