Skip to content

Development Guide

Welcome to the Echomine development documentation! This section contains detailed guides for contributors working on the project.

Quick Navigation

Getting Started

Development Standards

Overview

Echomine follows strict development practices to ensure quality, type safety, and maintainability. All contributors must follow these standards.

Core Principles

  1. Test-Driven Development (TDD)
  2. Write tests FIRST (RED phase)
  3. Implement minimal code to pass (GREEN phase)

  4. Refactor while keeping tests green (REFACTOR phase)

  5. Type Safety

  6. mypy --strict must pass with zero errors
  7. All functions must have type hints

  8. No Any types in public API

  9. Library-First Architecture

  10. Core functionality in src/echomine/ (importable library)
  11. CLI wraps library, never the reverse

  12. All features available programmatically

  13. Memory Efficiency

  14. O(1) memory usage via streaming
  15. ijson for parsing large files
  16. Generator patterns for all iterations

For complete development guidelines, see CONTRIBUTING.md.

Development Workflow Overview

graph TD
    A[Create Feature Branch] --> B[Write Failing Test RED]
    B --> C[Run Test - Verify Failure]
    C --> D[Implement Code GREEN]
    D --> E[Run Test - Verify Pass]
    E --> F[Refactor]
    F --> G{More Tests?}
    G -->|Yes| B
    G -->|No| H[Run Quality Checks]
    H --> I[mypy --strict]
    H --> J[ruff check/format]
    H --> K[pytest --cov]
    I --> L{All Pass?}
    J --> L
    K --> L
    L -->|No| M[Fix Issues]
    M --> H
    L -->|Yes| N[Commit & Push]
    N --> O[Create PR]

Quick Reference Commands

Testing

# All tests with coverage
pytest --cov=echomine --cov-report=term-missing

# Unit tests only (fast)
pytest tests/unit/ -v

# Watch mode (requires pytest-watch)
ptw -- tests/unit/

Type Checking

# Strict type checking
mypy --strict src/echomine/

# Check with tests too
mypy --strict src/echomine/ tests/

Linting and Formatting

# Auto-fix linting issues
ruff check --fix src/ tests/

# Format code
ruff format src/ tests/

# Check without making changes
ruff check src/ tests/
ruff format --check src/ tests/

Pre-Commit

# Run all hooks
pre-commit run --all-files

# Run specific hook
pre-commit run mypy --all-files

Documentation

# Build docs locally
mkdocs build

# Serve docs with live reload
mkdocs serve

# Deploy to GitHub Pages
mkdocs gh-deploy

Project Structure

echomine/
├── src/echomine/           # Library (importable, reusable)
│   ├── models/             # Pydantic data models
│   ├── protocols/          # Protocol definitions
│   ├── adapters/           # Provider implementations
│   ├── search/             # Search and ranking
│   ├── utils/              # Utilities (logging, exceptions)
│   └── cli/                # CLI commands (wraps library)
├── tests/
│   ├── unit/               # Fast, isolated tests (70%)
│   ├── integration/        # Component interaction (20%)
│   ├── contract/           # Protocol compliance (5%)
│   ├── performance/        # Benchmarks (5%)
│   └── fixtures/           # Test data
├── docs/                   # Documentation (mkdocs)
├── specs/                  # Feature specifications
└── .claude/                # AI agent coordination

Development Standards

Code Quality Gates

All code must pass these checks before merging:

  • ✅ Tests: pytest passes with >80% coverage
  • ✅ Type Checking: mypy --strict passes with zero errors
  • ✅ Linting: ruff check passes
  • ✅ Formatting: ruff format --check passes
  • ✅ Documentation: All public APIs have docstrings
  • ✅ Conventional Commits: Commit messages follow format

Constitution Principles

The project follows 8 constitution principles (non-negotiable):

  1. Library-First Architecture
  2. CLI Interface Contract (stdout/stderr separation)
  3. Test-Driven Development (TDD mandatory)
  4. Observability & Debuggability (JSON logs)
  5. Simplicity & YAGNI
  6. Strict Typing Mandatory (mypy --strict)
  7. Multi-Provider Adapter Pattern
  8. Memory Efficiency & Streaming

For details, see Architecture or specs/001-ai-chat-parser/constitution.md.

Getting Help

Next Steps

  1. New to the project? Start with Setup Guide
  2. Ready to code? Review Workflows
  3. Writing tests? See Testing Guide
  4. Type errors? Check Type Checking Guide
  5. Updating docs? Read Documentation Guide

Last Updated: 2025-11-28