Skip to content

ADR 0001 — Initial Architecture: Modular Monolith + Python-Only + File-First

  • Status: accepted
  • Date: 2026-05-22
  • Deciders: principal-architect (eric)
  • Supersedes: —
  • Superseded by: —
  • Related: ADR-0002

Context

Starting the mult-agentes framework, we need to decide the foundational architecture: language, runtime, deployment model, package boundaries. Wrong choices here are 10× harder to undo than later choices, so this ADR locks them in.

Constraints driving the decision: - Single-operator (Eric) for foreseeable future — bus factor 1 needs simplicity - Goal is documental + governance framework, not a SaaS product - All initial work is local; no production users yet - Future-runtime (LangGraph) must integrate cleanly later - Cross-platform (Windows + macOS + Linux) is required - Cost ceiling $50/mo for dev

Options considered

Option A — Python + modular monolith + file-first

  • ✅ Single language reduces cognitive load
  • ✅ Filesystem as v1.0 store works without infra setup
  • ✅ Modular monolith allows extracting microservices later if needed
  • ✅ PyYAML is the only runtime dep
  • ✅ Audit scripts and registry are file-based — git is the audit trail
  • ❌ Eventually needs runtime infra (Postgres, Redis) for Fase D+

Option B — Node/TypeScript + LangGraph TypeScript SDK directly

  • ✅ LangGraph TypeScript SDK is mature
  • ✅ Many ecosystem tools (npm)
  • ❌ Cross-platform with native deps brittle on Windows
  • ❌ Eric not equally productive in TypeScript at v1.0
  • ❌ Locks into Node runtime decisions early

Option C — Polyglot (Python core + Node tools)

  • ✅ Best-of-both
  • ❌ Bus factor 1 + polyglot = high maintenance burden
  • ❌ Premature complexity

Option D — Custom DSL on top of YAML

  • ✅ Maximum control
  • ❌ No leverage from ecosystem
  • ❌ Time-to-MVP measured in years

Decision

Adopt Option A. Python 3.12+, modular monolith, filesystem-first, PyYAML as sole runtime dep.

When Fase D lands, LangGraph integration will use the Python SDK; this ADR's choice keeps that path open.

Consequences

Positive

  • Setup is pip install pyyaml and clone — runs on any developer machine
  • Audits are pure Python over files — no DB to migrate
  • Single language for everything (scripts, audit, future runtime)
  • Eric's productivity high in Python; reduces single-operator risk

Negative

  • Performance ceiling: Python single-thread limits parallelism; matters at scale (Fase N)
  • Eventually need Postgres for prod; that's another ADR (deferred)
  • LangGraph integration cost (Fase D) is significant — separate decision via INTEGRATION-SPEC

Neutral

  • Modular monolith means later microservice extraction is possible but not free
  • Filesystem storage is simple but doesn't scale past single-node — explicit trade-off for v1.0

Compliance

  • Rule 1 (Documentation is code): this ADR is the source-of-truth for these choices
  • Rule 7 (immutable after accept): this ADR is now read-only; any change is a successor ADR

Implementation references

  • Project structure: _framework/PROJECT-STRUCTURE.md (template instance for THIS project — to be authored)
  • Blueprint: _framework/BLUEPRINT.md
  • Constraints: _framework/CONSTRAINTS.md