Solution Overview

Purpose

Explain the overall solution to a new developer before they read detailed designs.

Example

Show a worked example of this artifact

---
ddx:
  id: helix.solution-overview
  type: solution-overview
  authoring:
    home: repo
---
# HELIX solution overview

## Purpose and audience

HELIX gives software teams and their agents a shared set of documents and
rules for keeping product intent, designs, tests, and implementation aligned.
Start here to understand the system; use the [developer guide](https://github.com/DocumentDrivenDX/helix/blob/main/docs/guide/developer/developer-guide.md)
to make a change. This is an explanatory view of the current repository.
[Architecture](https://github.com/DocumentDrivenDX/helix/blob/main/docs/helix/02-design/architecture.md) governs system structure; the
[product requirements](https://github.com/DocumentDrivenDX/helix/blob/main/docs/helix/01-frame/prd.md) govern product scope.

## System map

The self-hosted HELIX pilot includes a presentation rendering with the same
entities and arrow directions as this semantic view:

![HELIX solution overview](https://raw.githubusercontent.com/DocumentDrivenDX/helix/main/docs/helix/02-design/diagrams/solution-overview.png)

[Editable SVG](https://github.com/DocumentDrivenDX/helix/blob/main/docs/helix/02-design/diagrams/solution-overview.svg) ·
[Design and visual review](https://github.com/DocumentDrivenDX/helix/blob/main/docs/helix/02-design/diagrams/solution-overview-design.md)

The shaded region identifies HELIX-owned content. Dashed arrows show guidance
or constraints; solid arrows show actions or information. The catalog summarizes
templates, prompts, metadata, and mode contracts. Repository paths and omitted
packaging/validation mechanics remain in the adjacent reference material.

Question: how does a team's request become a project document?
Arrows describe information or actions; boxes are content or actors, not running services.

```mermaid
flowchart LR
    Team[Software team] -->|asks through| Runtime[Agent runtime]
    Runtime -->|loads| Skill[HELIX routing skill]
    Marker[Project .helix.yml] -->|bounds scope for| Skill
    Catalog[Templates, prompts, metadata, mode contracts] -->|guides| Skill
    Skill -->|authors and reconciles| Docs[Project artifact instances]
    Docs -->|govern authorized execution by| Runtime
```

The runtime provides model access, file operations, execution, and source
control. HELIX supplies portable Markdown and YAML content plus one routing
skill. A request to plan does not authorize implementation.

## Parts and boundaries

| Part | Responsibility | Where to inspect |
|---|---|---|
| Routing skill | Resolve project scope, catalog, and workflow mode | `skills/helix/SKILL.md` |
| Methodology | Authority order, authoring rules, mode behavior | `workflows/modes/`, `workflows/artifact-schema.md` |
| Artifact catalog | Define each document type through template, prompt, metadata, example | `workflows/activities/*/artifacts/` |
| Type graph | Describe catalog relationships; generated from metadata | `workflows/graph.yml`, `scripts/generate_graph.py` |
| Project documents | Apply HELIX to HELIX itself | `docs/helix/` |
| Delivery tooling | Validate, package, and publish source content | `tests/`, `scripts/`, `docs/website/`, `website/` |

The project marker declares active document roots. Catalog definitions under
`workflows/` are maintained by contributors; ordinary adopting-project authoring
writes instances under the marker's root. Runtime integration is governed by
[CONTRACT-003](https://github.com/DocumentDrivenDX/helix/blob/main/docs/helix/02-design/contracts/CONTRACT-003-ddx-adapter-boundary.md).

## Critical flows

- **Author a document:** resolve marker and catalog, choose a mode, read governing
  artifacts and type instructions, write within scope, validate, review.
  Follow the [end-to-end walkthrough](https://github.com/DocumentDrivenDX/helix/blob/main/docs/helix/02-design/architecture-walkthrough.md).
- **Change the methodology:** edit canonical content, regenerate derived graph
  and reference pages as applicable, run repository gates, review the diff.
  Follow the developer guide's change recipes.
- **Deliver to a runtime:** package the same skill and catalog with generated
  references. `tests/validate-plugin-package.sh` checks source/package agreement.
  Installation instructions live in [docs/install](https://github.com/DocumentDrivenDX/helix/blob/main/docs/install/README.md).

## Vocabulary and reading path

An **artifact type** is a reusable document definition; an **instance** is a
project's document made from it. A **flow** applies a methodology to a marker's
bounded root. A **mode** is a workflow inside the single public `helix` skill.
A **concern** supplies cross-cutting practices such as module boundaries.

Read this overview → architecture walkthrough → developer guide for a first
contribution. Consult Architecture for structural decisions, the catalog for
document contracts, and [installation guidance](https://github.com/DocumentDrivenDX/helix/blob/main/docs/install/README.md) for host setup.

## Maintenance

Contributors update this map when routing, packaging, catalog ownership, or
artifact boundaries change. Review it alongside Architecture. Check every
linked path and trace the critical flow after such changes; generated graph
and reference pages remain derived outputs. This pilot has repository evidence,
but has not yet been tested by an unfamiliar developer.

Reference

Activity	Design — Decide how to build it. Capture trade-offs, contracts, and architecture decisions.
Default location	`docs/helix/02-design/solution-overview.md`
Requires	None
Enables	None
Generation prompt	Show the full generation prompt # Solution Overview authoring prompt Explain the overall solution to a new developer before they read detailed designs. This is a navigational projection of governing artifacts, not a new source of requirements or structural decisions. Link to Architecture, requirements, and relevant contracts. Identify current versus proposed views and uncertainty. Use one readable system map with labeled arrows, boundaries, and a legend. For content libraries or batch tools, draw actual content and execution actors; do not invent services to fill a conventional architecture diagram. Name concrete source locations and two or three critical flows. Link to a walkthrough and developer guide. Define unfamiliar vocabulary locally. Keep setup commands in the developer guide and structural decisions in Architecture. Name update triggers and the maintainer role. Check every source link. ## 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 field guide, use the architecture field guide profile and reusable prompt in `workflows/references/diagram-design.md`. Start with `workflows/references/architecture-plate.html`; replace all worked-example facts. Keep the numbered walkthrough, sources, limits, offline delivery, mobile and print review. Reference HTML supplies styling ideas, never project authority.
Template	Show the template structure --- ddx: id: solution-overview authoring: home: repo --- # Solution Overview ## Purpose and audience [System purpose, reader task, current/proposed state, and governing artifact links.] ## System map [Question, audience, intended takeaway, current/proposed state, and legend: actors, boundaries, and labeled information/action arrows.] [For a presentation version, follow `workflows/references/diagram-design.md`. Embed the rendered diagram and link editable vector source, export/rebuild instructions, and visual-review evidence. Keep the semantic source below; record simplifications and review both views for matching meaning.] ```mermaid flowchart LR Actor[User or agent] -->\|requests action from\| System[System] ``` [Optional developer HTML: link an offline architecture field guide using the `diagram-design.md` HTML profile and `architecture-plate.html` scaffold. Include numbered flow notes, governing sources, omissions, and rendered review evidence.] ## Parts and boundaries \| Part \| Responsibility \| Source / authority \| \|---\|---\|---\| \| [Part] \| [Owned behavior] \| [Concrete path or link] \| ## Critical flows [Two or three representative actions. Link one end-to-end architecture walkthrough and its proving tests; distinguish test intent from observed execution.] ## Vocabulary and reading path [Define unfamiliar terms; order links from overview to walkthrough, developer guide, and deeper references.] ## Maintenance [Maintainer role, changes that trigger updates, source/link checks, and uncertainty.]

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-overview.md
Signed: 2026-10-22T18:09:54Z
Content digest: sha256:1c6a8d3f…8e4d1072

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-10-22T18:09:54Z",
    "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-overview/",
        "digest": {
          "alg": "sha256",
          "value": "1c6a8d3ff4586ef5af920a5d251ee341f21c73becfbd165e0bea92578e4d1072"
        }
      }
    ],
    "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": "RZ97a0YGK6mg4j3VT0tCE-2tlykekG7SxHDecBp802924JCf90fNB71lfo62Es2y5tkl2N6gIhmTPxm-YnoICw",
      "signed_at": "2026-10-22T18:09:54Z"
    }
  ]
}

attestation file · issuer keys