Architecture Documentation

System architecture, design decisions, and technical deep-dives for the Dossier project.

Overview

This section contains comprehensive architectural documentation for developers and contributors who want to understand how Dossier is built.

Contents

• Overview - High-level architecture overview
• Architecture Decision Records (ADRs) - Key design decisions and rationale

System Components

Core Components

• @ai-dossier/core - Verification and parsing library
• @ai-dossier/cli - Command-line verification tool
• @ai-dossier/mcp-server - Model Context Protocol integration
• @ai-dossier/worktree-pool - Pre-warmed git worktree management

File Structure

• Monorepo organization (npm workspaces)
• Package interdependencies
• Build and publish pipeline

Security Architecture

• Cryptographic verification flow
• Key management (Ed25519, AWS KMS)
• Threat model and mitigations

See ../../security/ for detailed security architecture.

Architecture Decision Records

We use ADRs to document significant architectural decisions. Each ADR describes:

• The context and problem
• The decision made
• The consequences and trade-offs

Browse adr/ for all architecture decisions.

Design Principles

1. Security First: Cryptographic verification before execution
2. Simplicity: Minimal dependencies, clear abstractions
3. Extensibility: Plugin architecture for custom verifiers
4. Standards-Based: Follow OSS best practices
5. Developer Experience: Clear APIs, good documentation

For Contributors

• Understanding the codebase: Start with Overview
• Making architectural changes: Create an ADR in adr/
• Development setup: See CONTRIBUTING.md
• Workflows: Check ../contributing/workflows.md

External Resources

• Security Architecture
• Protocol Specification
• Main README

Rendered from docs/architecture/README.md in the repository. Edit it there.