t3mp3st/.aiwg/architecture/adr-001.md

ADR-001 — Retain a Local-First Modular Monolith

Metadata

• ADR ID: ADR-001
• Status: Accepted (retrospective baseline)
• Decision date: 2026-07-20
• Authors: Architecture baseline process
• Reviewers: Maintainer and safety-review roles; named human approval is not recorded
• Supersedes: None
• Current level: L3 — Accepted; current implementation predates the record

Context

Problem

T3MP3ST exposes a CLI, typed library, localhost HTTP/War Room, MCP, orchestration, tool adapters, evidence, and benchmarks from one Node/TypeScript package. The baseline needs an honest architectural description and an evolution rule that preserves local control without implying service isolation that does not exist.

Constraints

• Self-hosting and low-friction local installation are product values.
• CLI, library, HTTP, and MCP reuse the same domain behavior.
• Reports, evidence, configuration, and benchmark artifacts are primarily filesystem-backed.
• Real tool execution creates safety boundaries that cannot rely on process naming alone.
• No application database, distributed queue, multi-tenant identity service, or fleet control plane exists in the current baseline.

Stakeholders

• Operators need local control and visible artifacts.
• Integrators need stable typed and protocol surfaces.
• Safety reviewers need clear trust boundaries despite a shared runtime.
• Maintainers need coherent module ownership without distributed-system overhead.

Source Verification and Claim Tracking

Claim	Source	Verification
Runtime and delivery surfaces ship in one package	package.json, CLI/server/MCP/library entry points	Direct code/package inspection
HTTP defaults to local exposure	Server and Compose configuration	Static hardening tests and configuration inspection
No application database or queue is part of the baseline	Source/configuration inventory and SAD	Repository inspection; future addition triggers a new ADR

Decision

Treat the current system as a local-first modular monolith with ports/adapters characteristics. Delivery adapters and provider/tool adapters translate into shared domain modules in one Node.js runtime. Do not describe the architecture as microservices. Keep default HTTP exposure loopback-only and keep local artifacts under operator control.

Module boundaries are enforced through typed contracts, narrow adapters, tests, and architecture review. A hosted multi-tenant mode, distributed worker topology, or new durable shared store requires a new architecture baseline rather than being treated as a deployment toggle.

Alternatives Considered

Microservices now

• Pros: Process isolation, independently deployable components, per-service scaling.
• Cons: Adds network identity, distributed state, deployment, observability, and failure modes without evidenced fleet requirements.
• Why not chosen: The operational cost conflicts with local-first installation and would not automatically solve tool/target safety.

Plug-in processes for every domain

• Pros: Stronger fault and dependency isolation for tools/domains.
• Cons: IPC contracts, packaging complexity, lifecycle management, and difficult local debugging.
• Why not chosen: Selective external tool processes already exist; making every module a process is not justified by current evidence.

Unstructured single-module application

• Pros: Minimal ceremony.
• Cons: Unsafe coupling, poor test seams, and high regression risk across trust boundaries.
• Why not chosen: The codebase already has meaningful domain/adaptor modules whose contracts must remain reviewable.

Consequences

Positive

• One install and runtime supports all primary local surfaces.
• Shared typed modules reduce duplicated domain and safety logic.
• Filesystem artifacts remain inspectable and operator-controlled.

Negative

• Process boundaries do not enforce module isolation.
• A crash or resource-exhaustion defect can affect multiple domains.
• Scaling and hosted tenancy are not inherent properties of the architecture.

Operational Impact

• Maintainers must review dependency direction and surface parity.
• Local process startup, shutdown, filesystem permissions, and loopback exposure are architectural concerns.
• External tools remain separate processes with explicit argument, timeout, and output contracts.

Risks and Mitigations

Risk	Likelihood / impact	Mitigation
Unsafe cross-module coupling	Medium / High	Typed adapters, negative safety tests, ADR review for trust-boundary changes
Local process resource exhaustion	Medium / Medium	Finite timeouts, bounded ingest, controlled subprocess execution
Architecture mislabeled as distributed or production-fleet ready	Medium / High	SAD and maturity matrix; ADR-005 claim discipline

Implementation and Verification

• Key integration points: src/cli.ts, src/index.ts, src/server.ts, and src/mcp-server.ts compose shared domain code.
• State model: In-memory mission state plus local configuration, reports, evidence, and benchmark artifacts; no shared transactional store.
• Concurrency model: Node event-loop and explicitly managed parallel tasks/processes; shared mutable state remains process-local unless persisted as an artifact.
• Testing: Build/typecheck, entry-surface tests, local API hardening, agent parallelism, adapter tests, smoke and doctor commands.
• Regression guard: A change introducing a remotely exposed service, shared durable store, or distributed worker cannot close without an ADR/SAD update.

Definition of Done

• Context, decision, alternatives, consequences, and risks documented.
• Current implementation and tests identified.
• SAD describes the same architectural style.
• Named maintainer approval is recorded in a future review-incorporation log.
• Measured startup/shutdown and resource baselines are added before any related performance claim.

References

• @.aiwg/requirements/UC-003.md — Delivery-surface requirements.
• @.aiwg/requirements/nfr-register.md — Local security, portability, compatibility, and maintainability constraints.
• @.aiwg/architecture/software-architecture-doc.md — Current component, state, and deployment views.
• @src/cli.ts — CLI adapter.
• @src/index.ts — Library composition surface.
• @src/server.ts — Local HTTP/War Room adapter.
• @src/mcp-server.ts — MCP adapter.
• @docker-compose.yml — Local container deployment and volume/port configuration.
• @src/tests/local-api-hardening-static.test.ts — Local HTTP boundary evidence.

Review and Approval

This record captures an implemented brownfield decision. It is accepted as the documentation baseline, not as evidence of a historical architecture-board vote. A maintainer may amend or supersede it; that review must name the reviewer, date, conditions, and affected SAD sections.