Skip to content

Architecture

Purpose

Architecture is the highest-authority structural artifact in the Design activity. Its unique job is to describe the durable system shape: boundaries, containers, externally visible integrations, deployment topology, critical data flows, quality attributes, and structural tradeoffs.

For what belongs at this level versus Solution Design and Technical Design, see the zoom-stack matrix in workflows/activities/02-design/README.md.

Example

Show a worked example of this artifact
---
ddx:
  id: example.architecture.depositmatch
  authoring:
    home: repo
  depends_on:
    - example.product-vision.depositmatch
    - example.prd.depositmatch
    - example.concerns.depositmatch
    - example.feature-specification.depositmatch.csv-import
---

# Architecture

## Scope

This architecture covers DepositMatch v1: CSV import, match suggestion review,
exception handling, audit evidence, and reconciliation exports for small
bookkeeping firms. It is driven by the PRD goals of reducing weekly
reconciliation time, preserving reviewer trust, and keeping unresolved deposits
owned. Bank feeds, accounting platform sync, payroll, inventory, and tax
workflows are outside the v1 architecture boundary.

## Level 1: System Context

| Element | Type | Purpose | Protocol |
|---------|------|---------|----------|
| Maya, Reconciliation Lead | User | Imports exports, reviews suggestions, resolves exceptions | HTTPS browser |
| Andre, Firm Owner | User | Reviews firm-level reconciliation reports | HTTPS browser |
| DepositMatch | System | Reconciliation workspace and evidence store | HTTPS |
| Bank portal exports | External source | Provides deposit CSV files | Manual CSV export/upload |
| Accounting exports | External source | Provides invoice CSV files | Manual CSV export/upload |

```mermaid
graph TB
    Maya[Maya - Reconciliation Lead] -->|HTTPS| DM[DepositMatch]
    Andre[Andre - Firm Owner] -->|HTTPS| DM
    Bank[Bank portal exports] -->|CSV upload| DM
    Accounting[Accounting exports] -->|CSV upload| DM
```

## Level 2: Container Diagram

| Container | Technology | Responsibilities | Communication |
|-----------|------------|------------------|---------------|
| Web App | React 18, TypeScript 5 | Import workflow, mapping review, match review, exception queue, reports | HTTPS JSON to API |
| API Service | Node 20, Fastify 5, TypeScript 5 | Auth boundary, CSV upload orchestration, validation, matching commands, exception commands, exports | HTTPS JSON; SQL to PostgreSQL; S3 SDK |
| Matching Worker | Node 20, TypeScript 5 | Asynchronous match suggestion generation and confidence scoring | PostgreSQL job table; SQL |
| Database | PostgreSQL 16 on Amazon RDS | Clients, imports, source rows, invoices, deposits, matches, exceptions, audit log | TLS SQL |
| Source File Store | Amazon S3 with SSE-KMS | Encrypted uploaded CSV originals for audit and reprocessing | S3 API from API Service |
| Observability | CloudWatch Logs and Metrics | Application logs, import timing, worker failures, backup alarms | AWS agent/API |

```mermaid
graph TB
    Web[React Web App] -->|HTTPS JSON| API[Fastify API Service]
    API -->|TLS SQL| DB[(PostgreSQL 16)]
    API -->|S3 SDK| S3[(S3 Source File Store)]
    Worker[Matching Worker] -->|TLS SQL| DB
    API -->|job rows| DB
    API -->|logs/metrics| CW[CloudWatch]
    Worker -->|logs/metrics| CW
```

## Level 3: Component Diagram

The API Service needs component detail because CSV import, traceability, and
matching are coupled at the boundary.

| Component | Container | Purpose | Notes |
|-----------|-----------|---------|-------|
| Upload Controller | API Service | Receives bank and invoice CSV uploads for one client import session | Rejects non-CSV files before parsing |
| Mapping Service | API Service | Saves and applies per-client column mappings | Never imports rows with unresolved required mappings |
| CSV Validation Service | API Service | Validates amounts, dates, identifiers, duplicates, and required columns | Produces row-level rejection reasons |
| Import Commit Service | API Service | Atomically records accepted source rows and traceability fields | Transaction boundary for import confirmation |
| Evidence Service | API Service | Supplies source-row evidence to match review, exceptions, and exports | Reads normalized fields and source metadata |

```mermaid
graph TB
    Upload[Upload Controller] --> Mapping[Mapping Service]
    Mapping --> Validate[CSV Validation Service]
    Validate --> Commit[Import Commit Service]
    Commit --> Evidence[Evidence Service]
    Commit --> DB[(PostgreSQL)]
    Evidence --> DB
```

## Module Boundaries

**Source Applicability**: source; DepositMatch includes handwritten application code.

| Module | Responsibility / Owned Types | Public API | Allowed Dependencies | Forbidden Dependencies |
|--------|------------------------------|------------|----------------------|------------------------|
| api/domain | Owns matching invariants and core value types | Match decision and validation functions | Pure standard-library utilities | Services, Fastify, SQL, S3 SDK |
| api/application | Import and review orchestration; application-owned requests | Import and review operations; Contracts define shared surfaces | domain and application-owned ports | Fastify, concrete SQL/S3 adapters |
| api/adapters | HTTP, SQL and S3 integration; maps rows, vendor errors and transport DTOs | Implement application ports | domain, application, Fastify, SQL driver, S3 SDK | Other adapters' private implementation |
| api/bootstrap | Construct and connect concrete implementations | start | application and adapters | Domain business rules |

**Integration Owners**: PostgreSQL -> api/adapters/sql; S3 -> api/adapters/storage; Fastify -> api/adapters/http. Each translates representations and errors before calling application APIs.
**Construction Policy**: api/bootstrap is the composition root and supplies concrete adapters to application-owned ports.
**Boundary Check**: npm run check:boundaries (project-local import rules; invoked by pre-commit and CI).

Import cycles are forbidden. Domain state changes use validation functions;
mutable internals are private. Review checks public-type leakage and invariant
protection; the import gate alone cannot prove these semantics. The checker must
pass an allowed application-to-domain import and reject a domain-to-S3 import.

## Deployment

| Component | Infrastructure | Instances | Scaling | Backup / Recovery |
|-----------|----------------|-----------|---------|-------------------|
| Web App | S3 static hosting behind CloudFront, us-east-1 | 1 distribution | CDN-managed | Versioned S3 bucket; redeploy from CI |
| API Service | ECS Fargate service behind Application Load Balancer, us-east-1 | 2 tasks minimum | CPU > 60% for 5 minutes or p95 import latency > 3 seconds | Rolling deploy; previous task definition retained |
| Matching Worker | ECS Fargate service, us-east-1 | 1 task minimum | Job backlog > 100 for 5 minutes | Restart failed task; jobs remain in PostgreSQL |
| Database | Amazon RDS PostgreSQL 16, Multi-AZ | 1 primary, 1 standby | Vertical scaling by planned maintenance | PITR enabled; 15-minute RPO; 4-hour RTO |
| Source File Store | S3 bucket with SSE-KMS and versioning | Regional service | S3-managed | Versioning and lifecycle retention |

```mermaid
graph TB
    User[Browser] --> CF[CloudFront]
    CF --> S3Web[S3 Web App]
    User --> ALB[Application Load Balancer]
    ALB --> API1[ECS API Task A]
    ALB --> API2[ECS API Task B]
    Worker[ECS Matching Worker] --> RDS[(RDS PostgreSQL 16 Multi-AZ)]
    API1 --> RDS
    API2 --> RDS
    API1 --> FileS3[(S3 Source Files)]
    API2 --> FileS3
```

## Data Flow

```mermaid
sequenceDiagram
    participant Maya
    participant Web as React Web App
    participant API as Fastify API
    participant S3 as S3 Source File Store
    participant DB as PostgreSQL
    participant Worker as Matching Worker

    Maya->>Web: Upload bank and invoice CSVs
    Web->>API: POST import session files
    API->>S3: Store encrypted originals
    API->>API: Validate mapping and rows
    API->>DB: Commit accepted rows and rejection reasons
    API-->>Web: Import summary
    Maya->>Web: Confirm import summary
    Web->>API: Confirm import
    API->>DB: Mark import confirmed and enqueue matching job
    Worker->>DB: Read accepted rows and create suggestions
    Web->>API: Load match review queue
    API->>DB: Read suggestions with source-row evidence
    API-->>Web: Suggestions and evidence
```

## Quality Attributes

| Attribute | Target | Strategy | Verification |
|-----------|--------|----------|--------------|
| Import performance | Validate and summarize 10,000 total rows in under 5 seconds | Stream parse uploads, validate before commit, keep import commit transactional | Import benchmark in CI with representative CSV fixtures |
| Evidence traceability | 100% of accepted rows used in suggestions expose source file, row number, identifier, amount, and date | Preserve source metadata at import commit and read it through Evidence Service | Story tests for match review evidence and reconciliation export |
| Security | No raw financial row values in analytics or application logs | Structured logging allowlist; encrypted S3 and RDS storage; role-scoped audit access | Log scan tests, infrastructure review, access-control tests |
| Availability | 99.5% monthly availability for pilot firms | Two API tasks, RDS Multi-AZ, static web CDN, worker jobs persisted in DB | CloudWatch uptime and error-rate alarms |
| Disaster Recovery | 15-minute RPO and 4-hour RTO | RDS point-in-time recovery, S3 versioning, retained task definitions | Quarterly restore drill before paid launch |

## Decisions and Tradeoffs

| Decision | Status | Rationale | Follow-up |
|----------|--------|-----------|-----------|
| Use PostgreSQL 16 as the system of record | Accepted inline | Import traceability, matching evidence, exceptions, and audit logs need transactional consistency more than separate specialized stores. | Create ADR before production if another store is introduced. |
| Store uploaded CSV originals in encrypted S3 | Accepted inline | Preserving originals supports audit and reprocessing without bloating PostgreSQL. | Define retention period with firm owners and legal reviewer. |
| Use PostgreSQL-backed worker jobs for v1 | Accepted inline | Pilot volume does not justify a separate queue yet; keeping jobs in PostgreSQL reduces operational surface. | Revisit if matching backlog exceeds 100 jobs for 5 minutes repeatedly. |
| Keep bank feeds and accounting APIs outside v1 | Accepted by PRD non-goals | CSV import is enough to validate reviewer trust and weekly reconciliation speed. | Revisit when product priorities or integration requirements change. |

Reference

ActivityDesign — Decide how to build it. Capture trade-offs, contracts, and architecture decisions.
Default locationdocs/helix/02-design/architecture.md
RequiresNone
EnablesNone
InformsSolution Overview
Solution Design
Technical Design
ADR
Contract
Data Design
Security Architecture
Referenced bySolution Design
Technical Design
Deployment Checklist
Runbook
Monitoring Setup
HELIX documentsdocs/helix/02-design/architecture.md
Generation prompt
Show the full generation prompt
# Architecture Documentation Generation Prompt

Document the architecture views that the team actually needs to build, review,
operate, and evolve the system.

## Purpose

Architecture is the **highest-authority structural artifact** in the Design
activity. Its unique job is to describe the durable system shape: boundaries,
containers, externally visible integrations, deployment topology, critical data
flows, quality attributes, and structural tradeoffs.

For what belongs at this level versus Solution Design and Technical Design, see
the zoom-stack matrix in `workflows/activities/02-design/README.md`.

## Reference Anchors

Use these local resource summaries as grounding:

- `docs/resources/c4-model.md` grounds context, container, component, and
  deployment views as audience-specific structural diagrams.
- `docs/resources/sei-quality-attribute-scenarios.md` grounds measurable
  quality attributes and tradeoff reasoning.
- `docs/resources/microsoft-azure-well-architected-framework.md` grounds
  cross-cutting reliability, security, operations, performance, and cost
  tradeoffs.

## Focus
- Include only the C4 views that add information; omit empty or duplicate views.
- Keep boundaries, deployment shape, data flow, and quality attributes visible.
- Annotate major tradeoffs or constraints directly on the relevant view or summary.
- Remove generic architecture commentary.

## Boundary Test

See the zoom-stack matrix in `workflows/activities/02-design/README.md` for
which decisions belong at the system, feature, and story levels.

## Completion Criteria
- The views are understandable at a glance.
- Key boundaries and tradeoffs are visible.
- The document stays implementation-relevant.
- Containers name real technologies, not generic roles.
- Quality attributes have measurable targets and verification methods.
- Deployment names actual infrastructure shape, scaling, and backup approach.
- Major decisions link to ADRs or include an inline decision note.

## Module Boundary Evidence

For handwritten source, include Module Boundaries using the evidence format in
`workflows/concerns/modularity-and-encapsulation/practices.md`. Name actual
modules, responsibilities and owned types, minimal public APIs, permitted and
forbidden imports, integration owners/translation locations, construction policy,
and a concrete project-local boundary-check command. Classify domain types,
service orchestration, and integration representations separately. Apply the
selected architecture style without imposing inversion on classic-layered.
Source-free projects record applicability and reason; a tiny source project may
use one row. Legacy artifacts remain structurally valid without this section,
but current source feature readiness requires explicit adoption. Validate populated
fields; review semantics and confirm the check command exists before handoff.

## Explain a critical flow

When a new developer cannot follow the main flow from structural views alone,
include or link one end-to-end architecture walkthrough. Name its reader question,
current/proposed state, and diagram legend. Trace a concrete user action through
entrypoint, components, state changes, external interactions, failure handling,
and proving tests; link source locations and describe each check's limits.
For content systems, show content reads/writes and runtime actors without
inventing services. Distinguish an illustrative contract trace from an observed
runtime session. Name update triggers; avoid duplicating structural authority.

## Presentation visual quality

For conference or flagship visuals, apply `workflows/references/diagram-design.md`.
Start with the audience, one question, one takeaway, and semantic entities/edges.
Keep a maintainable semantic view and create an editable vector presentation
view when precise composition is needed. Use a named boundary, deliberate
hierarchy, readable labels, and consistent color/connector roles. Retain source
paths in adjacent prose. Render and inspect at full and preview sizes; correct
collisions before delivery. Record export provenance, semantic parity, deliberate
omissions, review evidence, and limits. Do not equate a successful export with
readability or an unperformed audience trial. This is an optional delivery
profile, not a new requirement for every reference diagram.

For a developer-facing HTML architecture field guide, use the HTML profile and
worked scaffold linked in `diagram-design.md`. Pair the map with a numbered
walkthrough, sources, and limits. Separate dense internals from the overview;
review connector routing, mobile overflow, offline use, and print output.
Template
Show the template structure
---
ddx:
  id: architecture
  authoring:
    home: repo
---

# Architecture

## Scope

[What system this architecture covers, what is deliberately outside the
architecture boundary, and which PRD/features/user journeys drive the design.]

## Level 1: System Context

| Element | Type | Purpose | Protocol |
|---------|------|---------|----------|
| [User/System] | User/External | [Interaction] | [HTTP/API/etc] |

```mermaid
graph TB
    %% Add users, system, and external dependencies
```

## Level 2: Container Diagram

| Container | Technology | Responsibilities | Communication |
|-----------|------------|------------------|---------------|
| [Name] | [Stack] | [What it does] | [Protocol/Format] |

```mermaid
graph TB
    %% Add containers: Web, API, DB, Queue, Worker, external systems
```

## Level 3: Component Diagram

Include only when a container needs internal structure to support downstream
design and review. Omit this section when container responsibilities are enough.

| Component | Container | Purpose | Notes |
|-----------|-----------|---------|-------|
| [Name] | [Container] | [Responsibility] | [Key decisions] |

```mermaid
graph TB
    %% Optional: add components inside the container that needs detail
```

## Module Boundaries

**Source Applicability**: [source or source-free; reason]

For source projects, complete every cell. A single module is sufficient for a
small program; do not add layers solely to fill the table. Source-free projects
may omit the table and fields below after recording the reason above.

| Module | Responsibility / Owned Types | Public API | Allowed Dependencies | Forbidden Dependencies |
|--------|------------------------------|------------|----------------------|------------------------|
| [Package/file] | [Responsibility and owned types] | [Exported names or Contract reference] | [Permitted imports] | [Forbidden imports] |

**Integration Owners**: [External system -> owning module and translation location, or None; reason]
**Construction Policy**: [Owner/location for wiring or deliberate local construction]
**Boundary Check**: [Concrete project-local command shared by local checks, pre-commit and CI]

## Deployment

| Component | Infrastructure | Instances | Scaling | Backup / Recovery |
|-----------|----------------|-----------|---------|-------------------|
| [Name] | [Cloud/service/runtime] | [Count] | [Trigger or limit] | [Backup/failover path] |

```mermaid
graph TB
    %% Add actual deployment topology
```

## Data Flow

```mermaid
sequenceDiagram
    %% Add sequence for the most important user journey or operational flow
```

## Quality Attributes

| Attribute | Target | Strategy | Verification |
|-----------|--------|----------|--------------|
| Availability | [Target] | [How architecture supports it] | [How checked] |
| Performance | [Target] | [How architecture supports it] | [How checked] |
| Security | [Target] | [Controls/boundaries] | [How checked] |
| Disaster Recovery | RTO: [target] / RPO: [target] | [Backup/failover strategy] | [How checked] |

## Decisions and Tradeoffs

| Decision | Status | Rationale | Follow-up |
|----------|--------|-----------|-----------|
| [ADR-NNN or inline decision] | [Accepted/Proposed] | [Why this shape wins] | [ADR, spike, or none] |

## Architecture Walkthrough (when useful)

[Explain one critical end-to-end scenario here, or link an adjacent walkthrough.
State the question, audience, and current/proposed state. Include an annotated
sequence with labeled interactions and a legend. Trace the user action through
entrypoint, components, data/state changes, integrations, failure handling, and
proving tests. For each step name source paths or contracts and what a reader
can verify. State verification limits and update triggers. Keep system decisions
in Architecture and feature behavior in Solution Design.]

### Presentation view (optional)

[When requested, apply `workflows/references/diagram-design.md`. Link editable
vector source and rendered export; record audience, takeaway, semantic source,
deliberate omissions, rebuild instructions, and full-size/preview review evidence.
Keep implementation paths in adjacent prose and preserve architectural meaning.]
Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition
model-primary
Issuer
HELIX helix
Signing key
ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source
artifact-types/design/architecture.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:9c239687…5930bb1b

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON
{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-11-16T15:52:45Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/artifact-types/design/architecture/",
        "digest": {
          "alg": "sha256",
          "value": "9c23968797fea58dbdcc49fd08cc3a085a34b4287ffc7a1bce53fb365930bb1b"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "oijfdMlfqEYQjwhgBpTR5l4ZfuXRCS3XW-cGQVmZJy4YjE47zQ0_4Ase_E1QL6AVIPeYTxxib_OqxW4VEOf1CQ",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}