Developer Guide & Contributing

Relevant source files

The following files were used as context for generating this wiki page:

• Docs/Architecture.md
• AGENTS.md
• CLAUDE.md
• Docs/Published/Code_Documentation/Docs_Site_Guide.md
• Docs/Release_Checklist.md
• Docs/Plans/2026-03-15-default-production-onboarding.md

Introduction

tldw_server is an open-source media analysis platform and research assistant designed to ingest, transcribe, and analyze various media formats through a FastAPI-based backend and a Next.js WebUI. The project follows an "incremental progress" philosophy, prioritizing stable, testable code that builds toward a long-term vision of a personal knowledge assistant.

This guide provides developers with the architectural mental model, technical standards, and procedural requirements for contributing to the codebase. It covers the transition from thin API endpoints to "fat" core modules, database management, and the rigorous testing standards required for all new features.
Sources: Docs/Architecture.md:10-25, CLAUDE.md:14-25

Architectural Mental Model

The system is structured as a layered architecture where logic is pushed away from the API endpoints and into domain-specific core modules.

The architecture follows a request flow where FastAPI routers validate input using Pydantic schemas, inject dependencies (Auth context, DB sessions), and delegate to the app/core/ directory for business logic.
Sources: Docs/Architecture.md:33-55, CLAUDE.md:113-140

Development Standards & Guidelines

Core Principles

Contributors must adhere to the following development philosophy:

• Incremental Progress: Small, testable changes are preferred over large "big bang" updates.
• Simplicity: Favor single responsibility per function and avoid premature abstractions.
• Thin Endpoints / Fat Core: API endpoints should focus on validation and response shaping, while app/core/ handles side effects and provider integration.
• Type Hinting: Comprehensive Python type hints are required for all function parameters and returns.
  Sources: CLAUDE.md:278-300, AGENTS.md:280-300

Coding Patterns

The project utilizes specific libraries and patterns to maintain consistency across the backend and frontend:

Component	Technology / Pattern	Description
Backend	FastAPI	Asynchronous REST and WebSocket APIs.
Validation	Pydantic	Models used for all API request/response validation.
Logging	Loguru	Centralized logging with from loguru import logger.
Database	SQLite/Postgres	Abstractions in core/DB_Management/; no raw SQL in endpoints.
Vector Store	ChromaDB	Per-user vector storage for RAG and embeddings.
Frontend	Next.js	Primary web client located in apps/tldw-frontend/.

Sources: Docs/Architecture.md:158-166, CLAUDE.md:100-111, AGENTS.md:115-125

Contribution Process

Feature Implementation Flow

Developers should follow a staged approach when adding new functionality:

1. Planning: Create an implementation plan (e.g., IMPLEMENTATION_PLAN_slug.md) breaking work into 3-5 stages.
2. Test-First Development: Write failing tests (red) before implementing logic.
3. Core Implementation: Add logic to /app/core/{feature}/.
4. API Integration: Define Pydantic schemas and create endpoints in /app/api/v1/endpoints/.
5. Refactor & Commit: Ensure code passes all tests and follows project linting.
   Sources: AGENTS.md:315-330, CLAUDE.md:310-325

Testing Strategy

The project maintains high testing standards, requiring over 80% code coverage. Tests must mirror the source code structure.

Unit Tests:* For individual functions and components.

• Integration Tests: For end-to-end API flows.
• Property-based Tests: Using frameworks like Hypothesis for complex logic.
• Postgres Fixture: AuthNZ tests automatically provision a Dockerized Postgres instance via the isolated_test_environment fixture.
  Sources: AGENTS.md:162-180, CLAUDE.md:195-215

Documentation Maintenance

The documentation site is built using MkDocs and the Material theme. It only publishes a curated subset of the Docs/ tree located in Docs/Published/.

Updating Documentation

• Source of Truth: Always edit files in Docs/, not Docs/Published/.
• Refresh Script: Run bash Helper_Scripts/refresh_docs_published.sh to sync changes to the published directory.
• Navigation: Update Docs/mkdocs.yml when adding new pages to ensure they appear in the sidebar.
  Sources: Docs/Published/Code_Documentation/Docs_Site_Guide.md:10-35, Docs/Published/Code_Documentation/Docs_Site_Guide.md:80-95

Release Hygiene

Before a release, developers must complete the comprehensive release checklist to ensure system stability.

Key Pre-release Tasks

• Versioning: Bump versions in pyproject.toml and package.json.
• Security: Run Bandit on the touched scope to check for vulnerabilities.
• Build Verification: Confirm pip install -e .[dev] and npm run build succeed in fresh environments.
• Migration Safety: Test database upgrade flows from previous versions.
  Sources: Docs/Release_Checklist.md:10-45, AGENTS.md:380-395

Conclusion

Contributing to tldw_server requires a balance of architectural discipline and incremental delivery. By pushing logic into core modules, maintaining strict testing coverage, and following the established documentation and release protocols, developers ensure the project remains a robust, self-hosted foundation for media analysis and research.