# 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**: 67 (66 numbers: ADR-001 to ADR-044 and ADR-050 to ADR-071, with two files numbered ADR-012). See [Numbering](#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](ADR-001-python-web-framework.md) | Python Web Framework Selection | Accepted | Flask as the web framework. | | [002](ADR-002-flask-extensions.md) | Flask Extensions and Dependencies | Accepted | A minimal dependency set; avoid Flask extensions where the standard library will do. | | [003](ADR-003-frontend-technology.md) | Front-end Technology Stack | Accepted | Server-rendered Jinja2 templates with minimal client-side code. | | [006](ADR-006-python-virtual-environment-uv.md) | Python Virtual Environment Management with uv | Accepted | uv manages the virtual environment and dependencies. | | [008](ADR-008-versioning-strategy.md) | Versioning Strategy | Accepted | Semantic Versioning, PEP 440 compatible. | | [009](ADR-009-git-branching-strategy.md) | Git Branching Strategy | Accepted | Simplified trunk-based development with feature branches and release tags. | | [012](ADR-012-flaky-test-removal.md) | Flaky Test Removal and Test Quality Standards | Accepted | Remove the multiprocessing migration tests and fix brittle assertions (done in v1.5.0). | | [015](ADR-015-phase-5-implementation-approach.md) | Phase 5 Implementation Approach | Accepted | Version jump 0.5.1 → 0.6.0 for Phase 5 (historical). | | [051](ADR-051-phase1-test-strategy.md) | 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](ADR-004-file-based-note-storage.md) | File-Based Note Storage Architecture | Accepted | Note content in Markdown files under `data/notes/YYYY/MM/`, metadata in SQLite. | | [013](ADR-013-expose-deleted-at-in-note-model.md) | Expose deleted_at Field in Note Model | Accepted | `deleted_at` on the Note dataclass for soft deletes. | | [020](ADR-020-automatic-database-migrations.md) | Automatic Database Migration System | Accepted | Numbered SQL migrations applied at startup and tracked in a table. | | [031](ADR-031-database-migration-system-redesign.md) | Database Migration System Redesign | Accepted | Baseline schema first, then migrations, so existing databases upgrade (implemented via ADR-032/033). | | [032](ADR-032-initial-schema-sql-implementation.md) | Initial Schema SQL Implementation for Migration System | Accepted | `INITIAL_SCHEMA_SQL` holds the baseline schema. | | [033](ADR-033-database-migration-redesign.md) | Database Migration System Redesign | Accepted | Frozen baseline schema; every later change only in migration files (v1.1.0). | | [037](ADR-037-migration-race-condition-fix.md) | Database Migration Race Condition Resolution | Accepted | SQLite `BEGIN IMMEDIATE` lock with retries so several gunicorn workers don't migrate at once. | | [041](ADR-041-database-migration-conflict-resolution.md) | Database Migration Conflict Resolution | Accepted | Handling a production database that fell into a migration edge case. | See also [database architecture](../architecture/database.md). ### Notes, slugs, media and search | ADR | Title | Status | Summary | |---|---|---|---| | [062](ADR-062-timestamp-based-slug-format.md) | Timestamp-Based Slug Format | Accepted | Default slugs are `YYYYMMDDHHMMSS` timestamps (v1.5.0); replaces ADR-007. | | [035](ADR-035-custom-slugs.md) | Custom Slugs in Micropub | Accepted* | Honour `mp-slug`, sanitized, with reserved names protected (v1.1.0). | | [034](ADR-034-full-text-search.md) | Full-Text Search with SQLite FTS5 | Accepted | FTS5 search over note content (v1.1.0). | | [057](ADR-057-media-attachment-model.md) | Media Attachment Model | Accepted | Social-media-style image attachments: up to 4 per note, ordered, with captions. | | [058](ADR-058-image-optimization-strategy.md) | Image Optimization Strategy | Accepted | Upload limits, automatic resizing and size variants. | ### Feeds | ADR | Title | Status | Summary | |---|---|---|---| | [014](ADR-014-rss-feed-implementation.md) | RSS Feed Implementation Strategy | Accepted* | RSS 2.0 feed; its WebSub deferral is superseded by ADR-071. | | [038](ADR-038-syndication-formats.md) | Multiple Syndication Format Support | Accepted | RSS, Atom and JSON Feed side by side (v1.1.2). | | [071](ADR-071-websub.md) | 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](ADR-059-full-feed-media-standardization.md) | 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](ADR-040-microformats2-compliance.md) | Strict Microformats2 Compliance | Accepted | Full h-entry, h-card and h-feed markup (v1.3.0, reviewed v2.8.0). | | [061](ADR-061-author-discovery.md) | Author Profile Discovery from IndieAuth | Accepted | The author h-card is read from `ADMIN_ME` and cached. | | [063](ADR-063-webmention-implementation.md) | 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](ADR-028-micropub-implementation.md) | Micropub Implementation Strategy | Accepted* | `/micropub` endpoint for creating posts (v1.0.0-rc.1); tokens now per ADR-064. | | [039](ADR-039-micropub-url-construction-fix.md) | Micropub URL Construction Fix | Accepted | Fix the double slash in returned post URLs. | | [067](ADR-067-micropub-update-delete.md) | Micropub update, delete, drafts and replies | Accepted | Micropub update, delete, drafts and replies (v2.4.0). | | [068](ADR-068-likes-and-reposts.md) | 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](../architecture/indieweb-protocols.md). ### Crossposting (POSSE) | ADR | Title | Status | Summary | |---|---|---|---| | [065](ADR-065-direct-syndication-posse.md) | Direct Syndication (POSSE) to GoToSocial | Accepted | Crosspost to GoToSocial/Mastodon-API servers from a background worker (v2.1.0). | | [066](ADR-066-bluesky-syndication.md) | Crossposting to Bluesky | Accepted | Bluesky as a second crosspost target (v2.2.0). | | [069](ADR-069-threads-syndication.md) | Crossposting to Threads | Accepted | Threads as a third target, with automatic token refresh (v2.6.0). | | [070](ADR-070-crosspost-links-and-cards.md) | Links and link cards in crossposts | Accepted | Keep note links in crossposts and build link cards for the linked page (v2.6.3). | ### Authentication (current) | ADR | Title | Status | Summary | |---|---|---|---| | [064](ADR-064-oidc-admin-login-and-builtin-indieauth-server.md) | OIDC Admin Login and Built-in IndieAuth Server | Accepted | Admin login via OIDC; StarPunk issues and verifies Micropub tokens itself (v2.0.0). | | [010](ADR-010-authentication-module-design.md) | Authentication Module Design | Accepted* | Single `auth.py` module and server-side sessions; the login flow is now ADR-064. | | [011](ADR-011-development-authentication-mechanism.md) | Development Authentication Mechanism | Accepted | `DEV_MODE` login bypass for local development only. | | [022](ADR-022-auth-route-prefix-fix.md) | Fix IndieAuth Callback Route Mismatch | Accepted | Auth routes live under `/auth` (v0.9.2). | ### Operations, errors and monitoring | ADR | Title | Status | Summary | |---|---|---|---| | [012](ADR-012-http-error-handling-policy.md) | HTTP Error Handling Policy | Accepted | Correct HTTP status codes (e.g. 404 for missing notes) across routes. | | [052](ADR-052-configuration-system-architecture.md) | Configuration System Architecture | Accepted | Environment variables with defaults, loaded in one module. | | [053](ADR-053-performance-monitoring-strategy.md) | Performance Monitoring Strategy | Accepted | Built-in, standard-library performance metrics (v1.1.1). | | [054](ADR-054-structured-logging-architecture.md) | Structured Logging Architecture | Accepted | Rotating log files with correlation IDs (v1.1.1). | | [055](ADR-055-error-handling-philosophy.md) | Error Handling Philosophy | Accepted | Layered handling: graceful degradation, clear user messages, detailed logs. | | [060](ADR-060-production-hotfix-metrics-dashboard.md) | Route Adapter for the Metrics Dashboard | Accepted | Adapt monitoring data to the dashboard template in the route (v1.1.1-rc.2). *Reconstructed.* | See also [deployment](../architecture/deployment.md). ## 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](ADR-005-indielogin-authentication.md) | IndieLogin Authentication Integration | Superseded by 064 | Admin login through indielogin.com. | | [007](ADR-007-slug-generation-algorithm.md) | Slug Generation Algorithm | Superseded by 062 | Slugs from the first words of the note. | | [016](ADR-016-indieauth-client-discovery.md) | IndieAuth Client Discovery Mechanism | Superseded by 019 | h-app markup for client discovery. | | [017](ADR-017-oauth-client-metadata-document.md) | OAuth Client ID Metadata Document Implementation | Superseded by 019 | OAuth client metadata endpoint. | | [018](ADR-018-indieauth-detailed-logging.md) | IndieAuth Detailed Logging Strategy | Superseded by 064 | Redacted HTTP logging of the IndieAuth login flow. | | [019](ADR-019-indieauth-correct-implementation.md) | IndieAuth Correct Implementation Based on IndieLogin.com API | Superseded by 025 | Draft of the IndieLogin.com PKCE flow. | | [021](ADR-021-indieauth-provider-strategy.md) | IndieAuth Provider Strategy | Superseded by 064 | Keep IndieLogin.com for admin login. | | [023](ADR-023-indieauth-client-identification.md) | IndieAuth Client Identification Strategy | Superseded by 064 | Visible h-app in the footer. | | [024](ADR-024-static-identity-page.md) | Static HTML Identity Pages for IndieAuth | Superseded by 064 | Standalone identity page pointing at indieauth.com. | | [025](ADR-025-indieauth-pkce-authentication.md) | IndieAuth Correct Implementation Based on IndieLogin.com API | Superseded by 064 | IndieLogin.com authentication with PKCE. | | [026](ADR-026-indieauth-token-exchange-compliance.md) | IndieAuth Token Exchange Compliance | Superseded by 064 | Token exchange parameters for the IndieAuth login. | | [027](ADR-027-indieauth-authentication-endpoint-correction.md) | IndieAuth Authentication Endpoint Correction | Superseded by 064 | Use the authentication (not token) endpoint for login. | | [029](ADR-029-micropub-indieauth-integration.md) | Micropub IndieAuth Integration Strategy | Superseded by 050, 064 | Built-in token endpoint for Micropub (v1.0.0-rc.1). | | [030](ADR-030-external-token-verification-architecture.md) | External Token Verification Architecture | Superseded by 043, 064 | Verify Micropub tokens at a configured external endpoint. | | [036](ADR-036-indieauth-token-verification-method.md) | IndieAuth Token Verification Method Diagnosis | Superseded by 064 | How to call the external token endpoint. | | [042](ADR-042-versioning-strategy-for-authorization-removal.md) | 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](ADR-043-CORRECTED-indieauth-endpoint-discovery.md) | IndieAuth Endpoint Discovery Architecture | Superseded by 064 | Discover the token endpoint from `ADMIN_ME` to verify tokens. | | [044](ADR-044-endpoint-discovery-implementation.md) | IndieAuth Endpoint Discovery Implementation Details | Superseded by 064 | Implementation details of ADR-043. | | [050](ADR-050-remove-custom-indieauth-server.md) | Remove Custom IndieAuth Server | Superseded by 064 | Remove the built-in authorization and token server (done in v1.0.0-rc.4). | | [056](ADR-056-no-selfhosted-indieauth.md) | 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.md` and `ADR-012-flaky-test-removal.md` (added 2025-12-16). Both are cited as plain "ADR-012": `starpunk/routes/admin.py` and early CHANGELOG entries mean the error policy, `tests/test_migration_race_condition.py` means 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 1. Use the next number after the highest existing one (currently ADR-072). 2. Name it `ADR-NNN-brief-descriptive-title.md`. 3. Follow the format of recent ADRs (e.g. ADR-070, ADR-071): ```markdown # ADR-NNN: Title ## Status Accepted (vX.Y.Z, YYYY-MM-DD) ## Context ## Decision ## Consequences ## Alternatives considered ``` 4. 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. 5. Add the ADR to this index. ## Related documentation - [../architecture/](../architecture/) — current system design - [../design/](../design/) — per-version implementation designs - [../standards/](../standards/) — coding and documentation standards - [../../CHANGELOG.md](../../CHANGELOG.md) — what changed in each release --- **Last Updated**: 2026-11-03 **Total ADR files**: 67