Skip to content

architecture.md

Latest commit

 

History

History
100 lines (70 loc) · 4.5 KB

architecture.md

File metadata and controls

100 lines (70 loc) · 4.5 KB

🏗️ System Architecture Overview

Concise overview of the template's design — see linked documents for details

Quick Reference: How To Use | Two-Layer Architecture | Workflow | Thin Orchestrator

Architecture Summary

The Research Project Template uses a Two-Layer Architecture with a Thin Orchestrator pattern:

  • Layer 1 — Infrastructure (infrastructure/): Generic, reusable build, validation, rendering, and reporting tools
  • Layer 2 — Projects (projects/{name}/): Project-specific code, manuscripts, and outputs
  • Scripts (scripts/, projects/{name}/scripts/): Thin orchestrators that import and use src/ methods — never implement algorithms

For the complete architecture guide, see Two-Layer Architecture.

Core Components

graph TB
    subgraph "Template Repository"
        INFRA[Infrastructure<br/>infrastructure/] --> |"provides tools"| PROJECT
        PROJECT[Project Code<br/>projects/*/src/] --> |"imported by"| SCRIPTS[Scripts<br/>projects/*/scripts/]
        SCRIPTS --> |"generate"| OUTPUTS[Outputs<br/>output/]
        TESTS[Tests<br/>tests/ & projects/*/tests/] --> |"validate"| PROJECT
        MANUSCRIPT[Manuscript<br/>projects/*/manuscript/] --> |"references"| OUTPUTS
    end

    classDef core fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef output fill:#fff3e0,stroke:#e65100,stroke-width:2px
    class INFRA,PROJECT,SCRIPTS,TESTS,MANUSCRIPT core
    class OUTPUTS output
Loading

Core pipeline (--core-only)

The default pipeline.yaml defines a DAG. With --core-only, stages tagged llm are omitted: eight core stages run (clean → setup → infra tests → project tests → analysis → PDF render → validate → copy). The full graph adds two optional LLM stages (review and translations) for ten core+LLM stages on the default full path (pipeline.yaml declares two additional opt-in bundle/archival stages). run.sh displays progress as [0/9]–[9/9] where stage 0 is the clean step.

Order Stage (from pipeline.yaml)
1 Clean Output Directories
2 Environment Setup
3 Infrastructure Tests
4 Project Tests
5 Project Analysis
6 PDF Rendering
7 Output Validation
8 Copy Outputs

Coverage gates: 90% for projects/{name}/src/, 60% for infrastructure/ (see docs/_generated/COUNTS.md). Full stage reference: RUN_GUIDE.md.

Run: uv run python scripts/execute_pipeline.py --project {name} --core-only

Key Principles

  1. Single Source of Truth — src/ is the authoritative implementation
  2. Thin Orchestrators — Scripts import src/ methods, never duplicate logic
  3. Test-Driven — Tests validate before implementation
  4. Reproducible — Deterministic RNG, fixed seeds, headless plotting
  5. Automated Validation — All components checked for coherence

Detailed Documentation

Topic Document
Full architecture guide two-layer-architecture.md
Thin orchestrator pattern thin-orchestrator-summary.md
Code placement decisions decision-tree.md
Development workflow workflow.md
Pipeline orchestration RUN_GUIDE.md
API reference api-reference.md

Development Rules

Troubleshooting

Layer Violation

Symptom: ModuleNotFoundError when infrastructure imports project code

Solution: Refactor - infrastructure must not depend on project code. Move shared logic to infrastructure.

Import Errors

Symptom: Scripts fail with import errors

Solution:

  • Use uv run python for proper environment
  • Ensure conftest.py adds src/ to path
  • Check thin orchestrator pattern: scripts import from src/, not implement

Quick Reference: Troubleshooting Guide