Gondulf/docs/architecture/overview.md

System Architecture Overview

Project Context

Gondulf is a self-hosted IndieAuth server implementing the W3C IndieAuth specification. It enables users to use their own domain as their identity when authenticating to third-party applications, providing a decentralized alternative to centralized authentication providers.

Key Differentiators

• Email-based authentication: v1.0.0 uses email verification for domain ownership
• No client pre-registration: Clients validate themselves through domain ownership verification
• Simplicity-first: Minimal complexity, production-ready MVP
• Single-admin model: Designed for individual operators, not multi-tenancy

Technology Stack

Core Platform

• Language: Python 3.10+
• Web Framework: FastAPI 0.104+
  • Chosen for: Native async/await, type hints, OAuth 2.0 support, automatic OpenAPI docs
  • See: /docs/decisions/ADR-001-python-framework-selection.md
• ASGI Server: uvicorn with standard extras
• Data Validation: Pydantic 2.0+ (bundled with FastAPI)

Data Storage

• Primary Database: SQLite 3.35+
  • Sufficient for 10s of users
  • Simple file-based backups
  • No separate database server required
• Database Interface: SQLAlchemy Core (NOT ORM)
  • Direct SQL-like interface without ORM complexity
  • Explicit queries, no hidden behavior
  • Simple schema management

Session/State Storage (v1.0.0)

• In-Memory Storage: Python dictionaries with TTL management
• Rationale:
  • No Redis in v1.0.0 per user requirements
  • Authorization codes are short-lived (10 minutes max)
  • Single-process deployment acceptable for MVP
  • Upgrade path: Can add Redis later without code changes if persistence needed

Development Environment

• Package Manager: uv (Astral Rust-based tool)
  • See: /docs/decisions/ADR-002-uv-environment-management.md
  • Direct execution model (no environment activation)
• Linting: Ruff + flake8
• Type Checking: mypy (strict mode)
• Formatting: Black (88 character line length)
• Testing: pytest with async, coverage, mocking

System Architecture

Component Diagram

┌─────────────────────────────────────────────────────────────────┐
│                        Client Application                        │
│                    (Third-party IndieAuth client)               │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTPS
                            │ IndieAuth Protocol
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                       Gondulf IndieAuth Server                   │
│  ┌────────────────────────────────────────────────────────────┐ │
│  │                    FastAPI Application                      │ │
│  │  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐  │ │
│  │  │ Authorization │  │    Token     │  │    Metadata     │  │ │
│  │  │   Endpoint    │  │   Endpoint   │  │    Endpoint     │  │ │
│  │  │  /authorize   │  │    /token    │  │   /.well-known  │  │ │
│  │  └──────┬───────┘  └──────┬───────┘  └────────┬────────┘  │ │
│  │         │                  │                    │           │ │
│  │         └──────────────────┼────────────────────┘           │ │
│  │                            │                                │ │
│  │  ┌─────────────────────────▼──────────────────────────────┐ │ │
│  │  │              Business Logic Layer                      │ │ │
│  │  │  ┌───────────────┐  ┌────────────┐  ┌──────────────┐  │ │ │
│  │  │  │ AuthService   │  │TokenService│  │DomainService │  │ │ │
│  │  │  │ - Auth flow   │  │ - Token    │  │ - Domain     │  │ │
│  │  │  │ - Email send  │  │   creation │  │   validation │  │ │
│  │  │  │ - Code gen    │  │ - Token    │  │ - TXT record │  │ │
│  │  │  │               │  │   verify   │  │   check      │  │ │
│  │  │  └───────────────┘  └────────────┘  └──────────────┘  │ │ │
│  │  └────────────────────────┬───────────────────────────────┘ │ │
│  │                           │                                 │ │
│  │  ┌────────────────────────▼──────────────────────────────┐ │ │
│  │  │               Storage Layer                           │ │ │
│  │  │  ┌──────────────────┐      ┌────────────────────────┐ │ │ │
│  │  │  │  SQLite Database │      │  In-Memory Store       │ │ │ │
│  │  │  │  - Tokens        │      │  - Auth codes (10min) │ │ │ │
│  │  │  │  - Domains       │      │  - Email codes (15min)│ │ │ │
│  │  │  └──────────────────┘      └────────────────────────┘ │ │ │
│  │  └───────────────────────────────────────────────────────┘ │ │
│  └────────────────────────────────────────────────────────────┘ │
└──────────┬──────────────────────────────────────┬───────────────┘
           │ SMTP                                  │ DNS
           ▼                                       ▼
  ┌────────────────┐                    ┌──────────────────┐
  │  Email Server  │                    │   DNS Provider   │
  │  (external)    │                    │   (external)     │
  └────────────────┘                    └──────────────────┘

Component Responsibilities

HTTP Endpoints Layer

Handles all HTTP concerns:

• Request validation (Pydantic models)
• Parameter parsing and type coercion
• HTTP response formatting
• Error responses (OAuth 2.0 compliant)
• CORS headers
• Rate limiting (future)

Business Logic Layer (Services)

Contains all domain logic, completely independent of HTTP:

AuthService:

• Authorization flow orchestration
• Email verification code generation and validation
• Authorization code generation (cryptographically secure)
• User consent management
• PKCE support (future)

TokenService:

• Access token generation (JWT or opaque)
• Token validation and introspection
• Token revocation (future)
• Token refresh (future)

DomainService:

• Domain ownership validation
• DNS TXT record checking
• Domain normalization
• Security validation (prevent open redirects)

Storage Layer

Provides data persistence:

SQLite Database:

• Access tokens (long-lived)
• Verified domains
• Audit logs
• Configuration

In-Memory Store:

• Authorization codes (TTL: 10 minutes)
• Email verification codes (TTL: 15 minutes)
• Rate limit counters (future)

Data Flow: Authorization Flow

1. Client → /authorize
   ↓
2. Gondulf validates client_id, redirect_uri, state
   ↓
3. Gondulf checks domain ownership (TXT record or cached)
   ↓
4. User enters email address for their domain
   ↓
5. Gondulf sends verification code to email
   ↓
6. User enters code
   ↓
7. Gondulf generates authorization code
   ↓
8. Gondulf redirects to client with code + state
   ↓
9. Client → /token with code
   ↓
10. Gondulf validates code, generates access token
   ↓
11. Gondulf returns token + me (user's domain)

Deployment Model

Target Deployment

• Platform: Docker container
• Scale: 10s of users initially
• Process Model: Single uvicorn process (sufficient for MVP)
• File System:
  • /data/gondulf.db - SQLite database
  • /data/backups/ - Database backups
  • /app/ - Application code

Configuration Management

• Environment Variables: All configuration via environment
• Secrets: Loaded from environment (SECRET_KEY, SMTP credentials)
• Config Validation: Pydantic Settings validates on startup

Backup Strategy

Simple file-based SQLite backups:

• Daily automated backups of gondulf.db
• Backup rotation (keep last 7 days)
• Simple shell script + cron
• Future: S3/object storage support

Security Architecture

Authentication Method (v1.0.0)

Email-based verification only:

• User provides email address for their domain
• Server sends time-limited verification code
• User enters code to prove email access
• No password storage
• No external identity providers in v1.0.0

Domain Ownership Validation

Two-tier validation:

1. TXT Record (preferred):

   • Admin adds TXT record: _gondulf.example.com = verified
   • Server checks DNS before first use
   • Result cached in database
   • Periodic re-verification (configurable)

2. Email-based (alternative):

   • If no TXT record, fall back to email verification
   • Email must be at verified domain (e.g., admin@example.com)
   • Less secure but more accessible for users

Token Security

• Generation: Cryptographically secure random tokens (secrets.token_urlsafe)
• Storage: Hashed in database (SHA-256)
• Transmission: HTTPS only (enforced in production)
• Expiration: Configurable (default 1 hour)
• Validation: Constant-time comparison (prevent timing attacks)

Privacy Principles

Minimal Data Collection:

• NEVER store email addresses beyond verification flow
• NEVER log user personal data
• Store only:
  • Domain name (user's identity)
  • Token hashes (security)
  • Timestamps (auditing)
  • Client IDs (protocol requirement)

Operational Architecture

Logging Strategy

Structured logging with appropriate levels:

• INFO: Normal operations (auth success, token issued)
• WARNING: Suspicious activity (failed validations, rate limit near)
• ERROR: Failures requiring investigation (email send failed, DNS timeout)
• CRITICAL: System failures (database unavailable, config invalid)

Log fields:

• Timestamp (ISO 8601)
• Level
• Event type
• Domain (never email)
• Client ID
• Request ID (correlation)

Privacy:

• NEVER log email addresses
• NEVER log full tokens (only first 8 chars for correlation)
• NEVER log user-agent or IP in production (GDPR)

Monitoring (Future)

• Health check endpoint: /health
• Metrics endpoint: /metrics (Prometheus format)
• Key metrics:
  • Authorization requests/min
  • Token generation rate
  • Email delivery success rate
  • Domain validation cache hit rate
  • Error rate by type

Upgrade Paths

Future Enhancements (Post v1.0.0)

Persistence Layer:

• Add Redis for distributed sessions
• Support PostgreSQL for larger deployments
• No code changes required (SQLAlchemy abstraction)

Authentication Methods:

• GitHub/GitLab provider support
• IndieAuth delegation
• WebAuthn for passwordless
• All additive, no breaking changes

Protocol Features:

• Token refresh
• Token revocation endpoint
• Scope management (authorization)
• Dynamic client registration

Operational:

• Multi-process deployment (gunicorn)
• Horizontal scaling (with Redis)
• Metrics and monitoring
• Admin dashboard

Constraints and Trade-offs

Conscious Simplifications (v1.0.0)

1. No Redis: In-memory storage acceptable for single-process deployment

   • Trade-off: Lose codes on restart (acceptable for 10-minute TTL)
   • Upgrade path: Add Redis when scaling needed

2. No client pre-registration: Domain-based validation sufficient

   • Trade-off: Must validate client_id on every request
   • Mitigation: Cache validation results

3. Email-only authentication: Simplest secure method

   • Trade-off: Requires SMTP configuration
   • Upgrade path: Add providers in future releases

4. SQLite database: Perfect for small deployments

   • Trade-off: No built-in replication
   • Upgrade path: Migrate to PostgreSQL when needed

5. Single process: No distributed coordination needed

   • Trade-off: Limited concurrent capacity
   • Upgrade path: Add Redis + gunicorn when scaling

Non-Negotiable Requirements

1. W3C IndieAuth compliance: Full protocol compliance required
2. Security best practices: No shortcuts on security
3. HTTPS in production: Required for OAuth 2.0 security
4. Minimal data collection: Privacy by design
5. Comprehensive testing: 80%+ coverage minimum

Documentation Structure

For Developers

• /docs/architecture/ - This directory
• /docs/designs/ - Feature-specific designs
• /docs/decisions/ - Architecture Decision Records

For Operators

• README.md - Installation and usage
• /docs/operations/ - Deployment guides (future)
• Environment variable reference (future)

For Protocol Compliance

• /docs/architecture/indieauth-protocol.md - Protocol implementation
• /docs/architecture/security.md - Security model
• Test suite demonstrating compliance

Next Steps

See /docs/roadmap/v1.0.0.md for the MVP feature set and implementation plan.

Key architectural documents to review:

• /docs/architecture/indieauth-protocol.md - Protocol design
• /docs/architecture/security.md - Security design
• /docs/roadmap/backlog.md - Feature prioritization