# 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

- [x] Context, decision, alternatives, consequences, and risks documented.
- [x] Current implementation and tests identified.
- [x] 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.