Joseph Magly
afc9dad1b2
* docs(policy): allow low-impact contributor courtesy cleanup * chore(aiwg): migrate to shared BT6 maintainer plugin * chore: reconcile delivery validation
127 lines
6.9 KiB
Markdown
127 lines
6.9 KiB
Markdown
# 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.
|