Skip to content

Solution Design

Purpose

Solution Design is the feature-level design artifact. Its unique job is to translate a Feature Specification into a selected technical approach, domain model, component decomposition, interface usage, and requirement-to-design traceability.

It applies Architecture, ADRs, Contracts, and Concerns to one feature or cross-component capability. For what belongs at this level versus Architecture 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.solution-design.depositmatch.csv-import
  authoring:
    home: repo
  depends_on:
    - example.feature-specification.depositmatch.csv-import
    - example.architecture.depositmatch
    - example.adr.depositmatch.postgresql-system-of-record
    - example.contract.depositmatch.import-session-api
---

# Solution Design

**Feature**: FEAT-001 - CSV Import and Column Mapping | **Artifact**:
`docs/helix/02-design/solution-designs/SD-001-csv-import-column-mapping.md`

## Scope

- Feature-level design for creating draft import sessions, uploading CSV files,
  mapping columns, validating rows, summarizing import results, and preserving
  traceability fields.
- Uses the DepositMatch Architecture, ADR-001 PostgreSQL system-of-record
  decision, API-001 import-session contract, and active concerns
  `csv-import-integrity`, `financial-data-security`, and
  `reviewer-auditability`.
- Does not design match suggestion scoring or accounting platform integrations.
- Story-level upload, mapping, and validation implementation details belong in
  TD-001, TD-002, and TD-003.

## Requirements Mapping

### Functional Requirements

| Requirement | Technical Capability | Component | Priority |
|-------------|----------------------|-----------|----------|
| UP-01 accept bank and invoice CSV files | Multipart upload endpoint creates a draft import session and stores encrypted originals | Upload Controller, Source File Store | P0 |
| UP-02 reject non-CSV files | File-type guard before parsing or storage | Upload Controller | P0 |
| MAP-01 require amount/date/identifier mappings | Mapping schema with required semantic fields per source type | Mapping Service | P0 |
| MAP-02 save confirmed mappings for reuse | Per-client mapping profiles keyed by source type | Mapping Service, PostgreSQL | P0 |
| VAL-01 reject missing required mapped columns | Header validation before row import | CSV Validation Service | P0 |
| VAL-02 reject invalid rows | Row validator for amount, date, and duplicate source identifiers | CSV Validation Service | P0 |
| SUM-01 show import summary | Import summary read model from validation results | Import Commit Service, API Service | P0 |
| TRC-01 preserve source metadata | Source row table stores file, row number, identifier, normalized amount/date | Import Commit Service, PostgreSQL | P0 |

### NFR Impact on Architecture

| NFR | Requirement | Architectural Impact | Design Decision |
|-----|-------------|----------------------|-----------------|
| Performance | 10,000 rows summarized in under 5 seconds | Validation must stream parse and batch database writes | Parse in API process, commit accepted rows in one transaction after summary confirmation |
| Security | No raw financial rows in analytics/logs | Logging must use event metadata only | Structured logging allowlist; raw rows only in encrypted S3/PostgreSQL |
| Reliability | Import confirmation atomic | Partial accepted-row commits are not allowed | Transaction boundary in Import Commit Service |

## Solution Approaches

### Approach 1: Parse and validate synchronously in the API

**Description**: The API parses uploaded CSV files, validates mappings and rows,
stores results, and returns an import summary.
**Pros**: Simple user feedback, fewer moving parts, easy pilot operation.
**Cons**: API task must handle peak import CPU and memory.
**Evaluation**: Selected for v1 because pilot imports are bounded at 10,000
rows and the feature needs immediate reviewer feedback.

### Approach 2: Store files and validate asynchronously in the worker

**Description**: The API stores files and enqueues validation work for the
Matching Worker.
**Pros**: Keeps upload endpoint fast and isolates parsing load.
**Cons**: Adds polling or notifications before mapping review; complicates
error recovery for a P0 workflow.
**Evaluation**: Rejected for v1. Revisit if import files exceed 10,000 rows or
validation regularly exceeds 5 seconds.

**Selected Approach**: Synchronous API validation with transactional commit
after reviewer confirmation.

**Architecture/ADR impact**: No change. This design applies the current
Architecture and ADR-001.

## Domain Model

```mermaid
erDiagram
    CLIENT ||--o{ IMPORT_SESSION : owns
    IMPORT_SESSION ||--|{ IMPORT_FILE : contains
    IMPORT_SESSION ||--o{ SOURCE_ROW : accepts
    CLIENT ||--o{ MAPPING_PROFILE : saves
    IMPORT_FILE ||--o{ VALIDATION_RESULT : produces
    SOURCE_ROW ||--o{ MATCH_EVIDENCE : supports
```

### Business Rules

- **BR-1** — Required source pair: A draft import session is not ready for
  mapping until it has one bank CSV and one invoice CSV.
- **BR-2** — Mapping before import: Accepted rows cannot be committed until
  required mappings exist for amount, date, and source identifier.
- **BR-3** — Validation before matching: Match suggestions cannot be created
  until the reviewer confirms an import summary.
- **BR-4** — Traceability preservation: Every accepted row must retain file
  identity, row number, source identifier, normalized amount, and normalized
  date.

## System Decomposition

### Component: Upload Controller

- **Purpose**: Receive CSV files and create draft import sessions.
- **Responsibilities**: Authenticate and authorize the client, enforce file
  type and size rules, store encrypted originals, return API-001 responses.
- **Requirements Addressed**: UP-01, UP-02.
- **Interfaces**: HTTP API `POST /v1/clients/{clientId}/import-sessions`; S3
  SDK; PostgreSQL.
- **Owned by TDs**: TD-001 upload endpoint and UI integration.

### Component: Mapping Service

- **Purpose**: Manage source-specific column mappings.
- **Responsibilities**: Load saved mappings, validate required semantic fields,
  save confirmed mappings by client and source type.
- **Requirements Addressed**: MAP-01, MAP-02, MAP-03.
- **Interfaces**: API Service internal module; PostgreSQL mapping tables.
- **Owned by TDs**: TD-002 mapping review workflow.

### Component: CSV Validation Service

- **Purpose**: Validate headers and rows before import confirmation.
- **Responsibilities**: Detect missing mapped columns, invalid amounts, invalid
  dates, duplicate source identifiers, and row-level rejection reasons.
- **Requirements Addressed**: VAL-01, VAL-02, VAL-03.
- **Interfaces**: API Service internal module; parsed CSV stream.
- **Owned by TDs**: TD-003 validation rules and test fixtures.

### Component: Import Commit Service

- **Purpose**: Commit accepted rows and import summary atomically.
- **Responsibilities**: Persist accepted source rows, rejection reasons,
  summary counts, and traceability fields.
- **Requirements Addressed**: SUM-01, SUM-02, TRC-01, TRC-02.
- **Interfaces**: PostgreSQL transaction; Evidence Service read model.
- **Owned by TDs**: TD-004 confirmation and source-row persistence.

### Component Interactions

```mermaid
graph TD
    Upload[Upload Controller] --> Mapping[Mapping Service]
    Mapping --> Validation[CSV Validation Service]
    Validation --> Summary[Import Summary]
    Summary --> Commit[Import Commit Service]
    Commit --> Rows[(Source Rows)]
    Commit --> Evidence[Evidence Service]
```

## Technology Rationale

Only feature-specific choices are listed here. System-wide choices remain in
Architecture and ADR-001.

| Layer | Choice | Why | Alternatives Rejected |
|-------|--------|-----|----------------------|
| CSV parser | Papa Parse | Already named in PRD technical context; supports browser and Node parsing patterns | Custom parser rejected because CSV edge cases are easy to mishandle |
| Validation model | Semantic field mapping per source type | Lets client-specific CSV headers map to stable DepositMatch concepts | Hard-coded column names rejected because pilot exports vary |
| Job trigger | PostgreSQL import confirmation state | Keeps matching jobs consistent with accepted rows | Separate queue rejected by ADR-001 for v1 simplicity |

## Traceability

| Requirement ID | Component | Design Element | Test Strategy |
|----------------|-----------|----------------|---------------|
| UP-01 | Upload Controller | Multipart import-session creation | API contract tests for API-001 and US-001 story tests |
| UP-02 | Upload Controller | File-type guard | API negative test with PDF upload |
| MAP-01 | Mapping Service | Required semantic mapping validation | Mapping unit tests with missing amount/date/identifier |
| VAL-02 | CSV Validation Service | Row-level amount/date/duplicate checks | Fixture-based validation tests |
| SUM-02 | Import Commit Service | Matching not enqueued before summary confirmation | Integration test around import status transition |
| TRC-02 | Evidence Service | Source-row evidence projection | Story test for match evidence display |

### Gaps

- [ ] Retention period for uploaded CSV originals needs legal/owner decision.
  Mitigation: keep retention configurable and create an ADR before paid launch.

## Concern Alignment

- **Concerns used**: `csv-import-integrity`, `financial-data-security`,
  `reviewer-auditability`, `a11y-wcag-aa`.
- **Constraints honored**: Required mapping and validation protect CSV
  integrity; raw financial rows stay out of analytics/logs; evidence fields are
  preserved for audit.
- **ADRs referenced**: ADR-001 PostgreSQL as system of record.
- **Departures**: None.

## Constraints & Assumptions

- **Constraints**: v1 supports CSV import only; no bank feed or accounting API
  sync.
- **Assumptions**: Pilot firm files fit within the 10 MB per-file limit and
  10,000-row validation target.
- **Dependencies**: API-001 import-session contract; encrypted S3 storage;
  PostgreSQL 16.

## Risks

| Risk | Prob | Impact | Mitigation |
|------|------|--------|------------|
| CSV layouts vary more than expected | H | M | Keep mappings semantic and per-client; collect pilot fixtures before launch. |
| Synchronous validation exceeds 5 seconds | M | M | Benchmark fixtures in CI; move validation to worker only if target fails repeatedly. |
| Reviewers distrust rejected-row explanations | M | H | Include row number, field, and plain-language reason for every rejection. |

## Diagnostic Flow

API and import workers carry the selected service-signal practices; the CI
runner supplies agent run diagnostics. Shared telemetry/capture/query definitions
belong in the pilot diagnostic Contract before dependent stories are ready.
Platform capture and runner capture are separate storage owners. The pilot must
prove mapping/correlation through an OTel receiver and investigate a synthetic
failed import; this example does not claim the pilot has run.

Reference

ActivityDesign — Decide how to build it. Capture trade-offs, contracts, and architecture decisions.
Default locationdocs/helix/02-design/solution-designs/SD-{id}-{name}.md
RequiresNone
EnablesNone
InformsTechnical Design
Test Plan
HELIX documentsdocs/helix/02-design/solution-designs/SD-002-first-class-principles.md
Generation prompt
Show the full generation prompt
# Solution Design Generation Prompt

Create a solution design that maps requirements to a concrete approach.

## Purpose

Solution Design is the **feature-level design artifact**. Its unique job is to
translate a Feature Specification into a selected technical approach, domain
model, component decomposition, interface usage, and requirement-to-design
traceability.

It applies Architecture, ADRs, Contracts, and Concerns to one feature or
cross-component capability. For what belongs at this level versus Architecture
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/arc42-solution-strategy.md` grounds feature-level approach,
  decomposition, interfaces, and concise design rationale.
- `docs/resources/c4-model.md` grounds component and interaction views that
  support feature-level decomposition.

## Focus
- Create a feature-level artifact named `docs/helix/02-design/solution-designs/SD-XXX-[name].md`.
- Show the main options and why the chosen one wins.
- Keep the domain model, decomposition, and tradeoffs concise.
- Cover cross-component system behavior and feature-level structure.
- Name interface usage or needed interface work at feature level, but keep exact
  API, CLI, event, schema, config, telemetry, and adapter surface in Contract
  artifacts. If the solution needs exact fields, commands, payloads, or error
  semantics, link to or request a Contract.
- Preserve only the decisions needed by build and test.
- Give every business rule a stable `**BR-n** —` line, numbered across the
  project and never reused. This section is the rules' single home: the
  feature specification's Task Model, stories, designs and tests cite `BR-n`
  instead of restating the rule.
- When people use the feature directly, add the optional Experience
  Traceability table (need, task, flow, view) and list any need or task with
  no flow or view under Gaps. Align checks this chain.
- Stay within the feature scope defined in the zoom-stack matrix
  (`workflows/activities/02-design/README.md`); update the governing artifact
  first if the feature forces a change at a higher level.

## 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
- Requirements are mapped.
- Tradeoffs are explicit.
- The chosen approach is clear.
- The output is clearly feature-level and disambiguated from a technical
  design.
- Every P0 requirement has a corresponding design element and test strategy.

## Diagnostic Flow

Apply selected `o11y-otel` practice sections to the feature's cross-component
flow. Identify instrumentation/capture owners and context boundaries. Reference
Contracts for exact surfaces; put system-wide logger, transport and backend
choices in Architecture/ADRs. Name receiver proof and diagnostic pilot slices
when relevant. A product that uses no models does not inherit GenAI conventions.

## 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.

## UMF Schema Reuse

Apply `workflows/references/umf-schemas.md` for schema, structured-interface, or
domain-model work. Inspect applicable UMF core, extensions, and domain packs;
reuse or compose by default. Record pinned sources, local additions, specific
exceptions, and semantic/projection limits. Declare `ddx.schemas` references to
the authoritative local sources so publication can render them in the UMF
browser. Contracts own exact shared surfaces; designs reference them.
Template
Show the template structure
---
ddx:
  id: SD-XXX
  authoring:
    home: repo
---

# Solution Design

**Feature**: [[FEAT-XXX]] | **Artifact**: `docs/helix/02-design/solution-designs/SD-XXX-[name].md`

## Scope

- Feature-level design artifact
- Use for cross-component behavior, main alternatives, domain model, and
  decomposition
- Do not use for one-story implementation details; those belong in `TD-XXX`
- Governing artifacts: [Architecture, ADRs, Contracts, Concerns]

## Requirements Mapping

### Functional Requirements

| Requirement | Technical Capability | Component | Priority |
|------------|---------------------|-----------|----------|
| [Business requirement] | [Technical implementation] | [Component] | P0/P1/P2 |

### NFR Impact on Architecture

| NFR | Requirement | Architectural Impact | Design Decision |
|-----|------------|---------------------|-----------------|
| Performance | [Metric] | [What this requires] | [How achieved] |
| Security | | | |
| Scalability | | | |

## Solution Approaches

### Approach 1: [Name]
**Description**: [Overview]
**Pros**: [Advantages]
**Cons**: [Disadvantages]
**Evaluation**: [Selected/Rejected: why]

### Approach 2: [Name]
[Same structure]

**Selected Approach**: [Which and why]

**Architecture/ADR impact**: [No change, or name required Architecture/ADR update]

## Domain Model

```mermaid
erDiagram
    %% [Define entities with attributes and relationships]
```

### Business Rules
- **BR-1** — [Rule]: [Description and implementation impact]

## System Decomposition

### Component: [Name]
- **Purpose**: [What it does]
- **Responsibilities**: [List]
- **Requirements Addressed**: [Which requirements]
- **Interfaces**: [How it communicates at feature level; exact shared surface links to Contract IDs]
- **Owned by TDs**: [Story-level work that will be designed later]

### Component Interactions
```mermaid
graph TD
    %% [Show component relationships]
```

## Technology Rationale

Only include feature-specific technology choices here. System-wide choices
belong in Architecture or ADRs.

| Layer | Choice | Why | Alternatives Rejected |
|-------|--------|-----|----------------------|
| Language | [Choice] | [Reason] | [Others] |
| Framework | [Choice] | [Reason] | [Others] |
| Database | [Choice] | [Reason] | [Others] |
| Infrastructure | [Choice] | [Reason] | [Others] |

## Traceability

| Requirement ID | Component | Design Element | Test Strategy |
|---------------|-----------|----------------|---------------|
| FR-001 | [Component] | [How addressed] | [How tested] |

### Experience Traceability

[Optional. For a feature people use directly: the chain from each need to the view that
serves it. Needs are PRD User Needs rows and tasks are Task Model rows, by
name.]

| Need | Task | Flow | View |
|------|------|------|------|
| [User Needs row] | [Task Model row] | [UF-XXX] | [UF-XXX-NN-view-name] |

### Gaps
- [ ] [Requirement not fully addressed]: [Mitigation]
- [ ] [Need or task with no flow or view]: [Mitigation]

## Concern Alignment

If the project has active concerns (`docs/helix/01-frame/concerns.md`), confirm
this design is consistent with them:

- **Concerns used**: [Which active concerns does this design rely on?]
- **Constraints honored**: [Any concern constraints that shaped this design?]
- **ADRs referenced**: [Concern-related ADRs that govern design choices here]
- **Departures**: [Any design choices that depart from concern practices? If so,
  an ADR should justify the departure.]

## Constraints & Assumptions

- **Constraints**: [Technical constraints and their design impact]
- **Assumptions**: [What we assume, risk if wrong]
- **Dependencies**: [External systems, libraries]

## Risks

| Risk | Prob | Impact | Mitigation |
|------|------|--------|------------|
| [Risk] | H/M/L | H/M/L | [Strategy] |

## Diagnostic Flow (when applicable)

For selected `o11y-otel` practices, describe cross-component signal ownership,
context propagation and capture/export/console flow. Reference Architecture/ADRs
for system choices and Contracts for exact telemetry/capture/query surfaces.
Identify the story slices proving OTel integration and agent diagnosis. Do not
redefine shared schemas or mandate a collector/backend for every component.

## 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.]

## Schema Basis (when applicable)

Follow `workflows/references/umf-schemas.md`. Name the inspected UMF core,
extensions/domain packs and versions; what is reused/composed/extended; or the
specific gap justifying an alternative. Reference the authoritative Contract
and source through `ddx.schemas`; explain unsupported semantics and tests.
Omit this section for work with no schema, structured interface, or domain model.
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/solution-design.md
Signed
2026-11-16T15:52:45Z
Content digest
sha256:8afb9bf8…91410c4a

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/solution-design/",
        "digest": {
          "alg": "sha256",
          "value": "8afb9bf85360a9001d06ac06e7eafac08fb6052be37ab2aca6284fa591410c4a"
        }
      }
    ],
    "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": "C811s-iTwbUq-Cukl0wNcnKZLBgSukyaX6WtgkZ0FmDrBUXo_7bPEOoN3trapD7kxuIA7UNi2BUwa-bZAg9dCQ",
      "signed_at": "2026-11-16T15:52:45Z"
    }
  ]
}