Files
StarPunk/docs/decisions/INDEX.md
T
PhilandClaude Opus 5.5 0716984958 docs: Bring all documentation up to date for v2.10.1
- architecture/: overview, technology stack, auth (OIDC + built-in
  IndieAuth), syndication (POSSE) rewritten; new database.md,
  deployment.md and indieweb-protocols.md; legacy stack marked historical
- decisions/: reconstructed ADR-060 and ADR-063; 31 status corrections
  (superseded auth ADRs, proposed -> accepted); INDEX rebuilt
- design/: reconstructed the v1.6.0 documents the webmention code cites;
  reports for 18 v2 releases without a design folder; INDEX rebuilt
- projectplan/: BACKLOG rewritten (shipped items removed, open issues from
  the reviews added); RELEASE.md for v2.0.0-v2.10.1; INDEX
- standards/: development setup (uv, tests, DEV_MODE), testing (CI test
  stage), git and release flow, versioning, coding standards, cookies
- README, CLAUDE.md, .env.example (every setting the code reads, with
  defaults) brought up to date
- 137 broken links repaired (old absolute paths, moved files); stale ADR
  references in code comments corrected (comments only)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 12:40:19 -07:00

204 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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