Files
StarPunk/docs/decisions/INDEX.md
T
PhilandClaude Opus 5.5 84411a16d9 feat: MCP server for AI clients (v2.15.0, ADR-075)
Add an MCP server at SITE_URL/mcp so AI assistants (claude.ai connectors,
Claude Code) can search, read and write notes.

- starpunk/mcp_server: official MCP SDK 2.3, stateless Streamable HTTP with
  JSON responses, served by uvicorn as a sidecar from the same image.
  Ten tools; writes go through the Micropub handlers.
- IndieAuth: RFC 8707 resource indicators bound to codes and tokens
  (migration 022), client ID metadata document + public client metadata,
  draft in scopes_supported, default MCP scopes, consent screen note.
- BACKGROUND_WORKERS_ENABLED flag so the sidecar runs no workers.
- Docs: ADR-075, architecture/mcp.md and updates; CHANGELOG.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 16:36:58 -07:00

16 KiB
Raw Blame History

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: 71 (70 numbers: ADR-001 to ADR-044 and ADR-050 to ADR-075, 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.

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 Accepted Poll GoToSocial, Bluesky and Threads for responses to crossposts and store them as webmentions; admin backfill (v2.13.0, amended v2.13.2–v2.13.3).

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).
075 MCP server for AI clients Accepted /mcp served by the official MCP SDK in a sidecar; StarPunk's IndieAuth server issues resource-bound tokens via client ID metadata documents (v2.15.0).

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).
074 Notifications through Apprise Accepted Notify the owner of new responses and crosspost/backfeed problems via the embedded Apprise library (v2.14.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.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-076).

  2. Name it ADR-NNN-brief-descriptive-title.md.

  3. 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
    
  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.


Last Updated: 2026-11-10 Total ADR files: 70