# Architectural Decision Records (ADRs) Index

This directory contains all Architectural Decision Records for StarPunk CMS. ADRs document significant architectural decisions, their context, rationale, and consequences.

## ADR Format

Each ADR follows this structure:
- **Title**: ADR-NNN-brief-descriptive-title.md
- **Status**: Proposed, Accepted, Deprecated, Superseded
- **Context**: Why we're making this decision
- **Decision**: What we decided to do
- **Consequences**: Impact of this decision

## All ADRs (Chronological)

### Foundation & Technology Stack (ADR-001 to ADR-009)
- **[ADR-001](ADR-001-python-web-framework.md)** - Python Web Framework Selection
- **[ADR-002](ADR-002-flask-extensions.md)** - Flask Extensions Strategy
- **[ADR-003](ADR-003-frontend-technology.md)** - Frontend Technology Stack
- **[ADR-004](ADR-004-file-based-note-storage.md)** - File-Based Note Storage
- **[ADR-005](ADR-005-indielogin-authentication.md)** - IndieLogin Authentication
- **[ADR-006](ADR-006-python-virtual-environment-uv.md)** - Python Virtual Environment with uv
- **[ADR-007](ADR-007-slug-generation-algorithm.md)** - Slug Generation Algorithm
- **[ADR-008](ADR-008-versioning-strategy.md)** - Versioning Strategy
- **[ADR-009](ADR-009-git-branching-strategy.md)** - Git Branching Strategy

### Authentication & Authorization (ADR-010 to ADR-027)
- **[ADR-010](ADR-010-authentication-module-design.md)** - Authentication Module Design
- **[ADR-011](ADR-011-development-authentication-mechanism.md)** - Development Authentication Mechanism
- **[ADR-016](ADR-016-indieauth-client-discovery.md)** - IndieAuth Client Discovery
- **[ADR-017](ADR-017-oauth-client-metadata-document.md)** - OAuth Client Metadata Document
- **[ADR-018](ADR-018-indieauth-detailed-logging.md)** - IndieAuth Detailed Logging
- **[ADR-019](ADR-019-indieauth-correct-implementation.md)** - IndieAuth Correct Implementation
- **[ADR-021](ADR-021-indieauth-provider-strategy.md)** - IndieAuth Provider Strategy
- **[ADR-022](ADR-022-auth-route-prefix-fix.md)** - Auth Route Prefix Fix
- **[ADR-023](ADR-023-indieauth-client-identification.md)** - IndieAuth Client Identification
- **[ADR-024](ADR-024-static-identity-page.md)** - Static Identity Page
- **[ADR-025](ADR-025-indieauth-pkce-authentication.md)** - IndieAuth PKCE Authentication
- **[ADR-026](ADR-026-indieauth-token-exchange-compliance.md)** - IndieAuth Token Exchange Compliance
- **[ADR-027](ADR-027-indieauth-authentication-endpoint-correction.md)** - IndieAuth Authentication Endpoint Correction

### Error Handling & Core Features (ADR-012 to ADR-015)
- **[ADR-012](ADR-012-http-error-handling-policy.md)** - HTTP Error Handling Policy
- **[ADR-013](ADR-013-expose-deleted-at-in-note-model.md)** - Expose Deleted-At in Note Model
- **[ADR-014](ADR-014-rss-feed-implementation.md)** - RSS Feed Implementation
- **[ADR-015](ADR-015-phase-5-implementation-approach.md)** - Phase 5 Implementation Approach

### Micropub & API (ADR-028 to ADR-029)
- **[ADR-028](ADR-028-micropub-implementation.md)** - Micropub Implementation
- **[ADR-029](ADR-029-micropub-indieauth-integration.md)** - Micropub IndieAuth Integration

### Database & Migrations (ADR-020, ADR-031 to ADR-037)
- **[ADR-020](ADR-020-automatic-database-migrations.md)** - Automatic Database Migrations
- **[ADR-031](ADR-031-database-migration-system-redesign.md)** - Database Migration System Redesign
- **[ADR-032](ADR-032-initial-schema-sql-implementation.md)** - Initial Schema SQL Implementation
- **[ADR-033](ADR-033-database-migration-redesign.md)** - Database Migration Redesign
- **[ADR-037](ADR-037-migration-race-condition-fix.md)** - Migration Race Condition Fix
- **[ADR-041](ADR-041-database-migration-conflict-resolution.md)** - Database Migration Conflict Resolution

### Search & Advanced Features (ADR-034 to ADR-036, ADR-038 to ADR-040)
- **[ADR-034](ADR-034-full-text-search.md)** - Full-Text Search
- **[ADR-035](ADR-035-custom-slugs.md)** - Custom Slugs
- **[ADR-036](ADR-036-indieauth-token-verification-method.md)** - IndieAuth Token Verification Method
- **[ADR-038](ADR-038-syndication-formats.md)** - Syndication Formats (ATOM, JSON Feed)
- **[ADR-039](ADR-039-micropub-url-construction-fix.md)** - Micropub URL Construction Fix
- **[ADR-040](ADR-040-microformats2-compliance.md)** - Microformats2 Compliance

### Architecture Refinements (ADR-042 to ADR-044)
- **[ADR-042](ADR-042-versioning-strategy-for-authorization-removal.md)** - Versioning Strategy for Authorization Removal
- **[ADR-043](ADR-043-CORRECTED-indieauth-endpoint-discovery.md)** - CORRECTED IndieAuth Endpoint Discovery
- **[ADR-044](ADR-044-endpoint-discovery-implementation.md)** - Endpoint Discovery Implementation Details

### Major Architectural Changes (ADR-050 to ADR-051)
- **[ADR-050](ADR-050-remove-custom-indieauth-server.md)** - Remove Custom IndieAuth Server
- **[ADR-051](ADR-051-phase1-test-strategy.md)** - Phase 1 Test Strategy

### v1.1.1 Quality & Production Readiness (ADR-052 to ADR-055)
- **[ADR-052](ADR-052-configuration-system-architecture.md)** - Configuration System Architecture
- **[ADR-053](ADR-053-performance-monitoring-strategy.md)** - Performance Monitoring Strategy
- **[ADR-054](ADR-054-structured-logging-architecture.md)** - Structured Logging Architecture
- **[ADR-055](ADR-055-error-handling-philosophy.md)** - Error Handling Philosophy

## ADRs by Topic

### Authentication & IndieAuth
ADR-005, ADR-010, ADR-011, ADR-016, ADR-017, ADR-018, ADR-019, ADR-021, ADR-022, ADR-023, ADR-024, ADR-025, ADR-026, ADR-027, ADR-036, ADR-043, ADR-044, ADR-050

### Database & Migrations
ADR-004, ADR-020, ADR-031, ADR-032, ADR-033, ADR-037, ADR-041

### API & Micropub
ADR-028, ADR-029, ADR-039

### Content & Features
ADR-007, ADR-013, ADR-014, ADR-034, ADR-035, ADR-038, ADR-040

### Development & Operations
ADR-001, ADR-002, ADR-003, ADR-006, ADR-008, ADR-009, ADR-012, ADR-015, ADR-042, ADR-051, ADR-052, ADR-053, ADR-054, ADR-055

## Superseded ADRs

These ADRs have been superseded by later decisions:
- **ADR-030** (old) - Superseded by ADR-043 (CORRECTED IndieAuth Endpoint Discovery)

## How to Create a New ADR

1. **Find the next sequential number**: Check the highest existing ADR number
2. **Use the naming format**: `ADR-NNN-brief-descriptive-title.md`
3. **Follow the template**:
   ```markdown
   # ADR-NNN: Title

   ## Status
   Proposed | Accepted | Deprecated | Superseded

   ## Context
   Why are we making this decision?

   ## Decision
   What have we decided to do?

   ## Consequences
   What are the positive and negative consequences?

   ## Alternatives Considered
   What other options did we evaluate?
   ```
4. **Update this index** with the new ADR

## Related Documentation
- **[../architecture/](../architecture/)** - Architectural overviews and system design
- **[../design/](../design/)** - Detailed design documents
- **[../standards/](../standards/)** - Coding standards and conventions

---

**Last Updated**: 2025-11-25
**Maintained By**: Documentation Manager Agent
**Total ADRs**: 55