# dczerwinskipl/nevo-specflow architecture

> Architecture diagram of the GitHub repository dczerwinskipl/nevo-specflow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dczerwinskipl/nevo-specflow
- Repository: https://github.com/dczerwinskipl/nevo-specflow

## Overview

Nevo SpecFlow is a spec-driven development framework: people use its CLI and served UI to work with specifications, documents, Git workspaces and managed agent Sessions. The Runtime exposes local authenticated workflows backed by the offline Engine; docs discovery/search and agent adapters are additional capabilities. The deterministic Specifications/Tasks workflow kernel exists in the Engine but is explicitly not wired to the Runtime, CLI or UI. Edges reflect README statements and the supplied source references; unsampled details are not inferred.

Main entry points: [`packages/specflow-engine/src/application.ts`](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/application.ts) (Engine boundary), [`packages/specflow-runtime/src/server/app.ts`](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/server/app.ts) (Runtime server), [`packages/specflow/src/program.ts`](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow/src/program.ts) (SpecFlow CLI), [`packages/specflow-docs/src/search/search.ts`](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-docs/src/search/search.ts) (Docs commands)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry points"]
  node_cli["SpecFlow CLI<br/>[program.ts]"]
  node_ui["SpecFlow UI<br/>[routes.tsx]"]
end

subgraph group_runtime["Local Runtime"]
  node_runtime_server["Runtime server<br/>[app.ts]"]
  node_auth_sessions["Auth and sessions<br/>[routes.ts]"]
  node_spec_overview["Specification overview"]
  node_spec_workspace["Specification workspace"]
  node_documents_read["Document reads<br/>[engine-source.ts]"]
  node_documents_write["Document writes"]
end

subgraph group_engine["Offline Engine"]
  node_engine_open["Engine access<br/>[engine-at.ts]"]
  node_engine["Engine boundary<br/>[application.ts]"]
  node_project_home[("Project Home<br/>[home.ts]")]
  node_workspace_registry[("Workspace registry<br/>[registry.ts]")]
  node_git["Git workspaces<br/>[git-instance.ts]"]
  node_workflow_kernel["Specs and Tasks<br/>[tasks.ts]"]
end

subgraph group_docs["Documentation discovery"]
  node_docs_cli["Docs commands<br/>[search.ts]"]
  node_docs_corpus["Repository corpus<br/>[repository.ts]"]
  node_embeddings["Semantic embeddings"]
end

subgraph group_agents["Agent workflow"]
  node_agent_adapters["Agent adapters<br/>[program.ts]"]
end

node_person(("Repository owner"))

node_person -->|"runs commands"| node_cli
node_person -->|"uses"| node_ui
node_cli -->|"opens engine"| node_engine_open
node_cli -->|"starts runtime"| node_runtime_server
node_cli -->|"registers commands"| node_docs_cli
node_ui -->|"uses served UI"| node_runtime_server
node_runtime_server -.->|"serves sessions"| node_auth_sessions
node_runtime_server -.->|"serves specifications"| node_spec_overview
node_runtime_server -.->|"serves workspace"| node_spec_workspace
node_runtime_server -.->|"serves reads"| node_documents_read
node_runtime_server -.->|"serves writes"| node_documents_write
node_engine -->|"resolves home"| node_project_home
node_engine -->|"verifies registration"| node_workspace_registry
node_workspace_registry -->|"reads home"| node_project_home
node_engine -.->|"manages worktrees"| node_git
node_spec_overview -->|"reads canonical specs"| node_engine
node_spec_workspace -->|"reads canonical specs"| node_engine
node_documents_read -->|"reads documents"| node_engine
node_documents_write -->|"applies changes"| node_engine
node_auth_sessions -->|"tracks execution"| node_engine
node_engine -.->|"owns workflow"| node_workflow_kernel
node_docs_cli -.->|"discovers content"| node_docs_corpus
node_docs_cli -.->|"supports semantic search"| node_embeddings
node_agent_adapters -.->|"exposes adapters"| node_cli

click node_cli "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow/src/program.ts"
click node_ui "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-ui/src/features/specs/routes.tsx"
click node_engine_open "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow/src/engine-at.ts"
click node_runtime_server "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/server/app.ts"
click node_auth_sessions "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/sessions/http/routes.ts"
click node_spec_overview "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/specs/overview/repository/engine-repository.ts"
click node_spec_workspace "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/specs/workspace/engine-repository.ts"
click node_documents_read "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/documents/content/engine-source.ts"
click node_documents_write "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/documents/write/engine-write-source.ts"
click node_engine "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/application.ts"
click node_project_home "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/project/home/home.ts"
click node_workspace_registry "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/project/workspace/registry/registry.ts"
click node_git "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/project/git-instance.ts"
click node_workflow_kernel "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/workflow/tasks/tasks.ts"
click node_docs_cli "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-docs/src/search/search.ts"
click node_docs_corpus "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-docs/src/corpus/repository.ts"
click node_embeddings "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-docs/src/embeddings/embedding-providers.ts"
click node_agent_adapters "https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow/src/program.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_ui toneBlue
class node_runtime_server,node_auth_sessions,node_spec_overview,node_spec_workspace,node_documents_read,node_documents_write toneAmber
class node_engine_open,node_engine,node_project_home,node_workspace_registry,node_git,node_workflow_kernel toneMint
class node_docs_cli,node_docs_corpus,node_embeddings toneRose
class node_agent_adapters,node_person toneIndigo
```

## Components

### User entry points

- [SpecFlow CLI](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow/src/program.ts): `packages/specflow/src/program.ts`
- [SpecFlow UI](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-ui/src/features/specs/routes.tsx): `packages/specflow-ui/src/features/specs/routes.tsx`

### Local Runtime

- [Runtime server](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/server/app.ts): `packages/specflow-runtime/src/server/app.ts`
- [Auth and sessions](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/sessions/http/routes.ts): `packages/specflow-runtime/src/features/sessions/http/routes.ts`
- [Specification overview](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/specs/overview/repository/engine-repository.ts): `packages/specflow-runtime/src/features/specs/overview/repository/engine-repository.ts`
- [Specification workspace](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/specs/workspace/engine-repository.ts): `packages/specflow-runtime/src/features/specs/workspace/engine-repository.ts`
- [Document reads](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/documents/content/engine-source.ts): `packages/specflow-runtime/src/features/documents/content/engine-source.ts`
- [Document writes](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-runtime/src/features/documents/write/engine-write-source.ts): `packages/specflow-runtime/src/features/documents/write/engine-write-source.ts`

### Offline Engine

- [Engine access](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow/src/engine-at.ts): `packages/specflow/src/engine-at.ts`
- [Engine boundary](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/application.ts): `packages/specflow-engine/src/application.ts`
- [Project Home](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/project/home/home.ts): `packages/specflow-engine/src/project/home/home.ts`
- [Workspace registry](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/project/workspace/registry/registry.ts): `packages/specflow-engine/src/project/workspace/registry/registry.ts`
- [Git workspaces](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/project/git-instance.ts): `packages/specflow-engine/src/project/git-instance.ts`
- [Specs and Tasks](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-engine/src/workflow/tasks/tasks.ts): `packages/specflow-engine/src/workflow/tasks/tasks.ts`

### Documentation discovery

- [Docs commands](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-docs/src/search/search.ts): `packages/specflow-docs/src/search/search.ts`
- [Repository corpus](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-docs/src/corpus/repository.ts): `packages/specflow-docs/src/corpus/repository.ts`
- [Semantic embeddings](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow-docs/src/embeddings/embedding-providers.ts): `packages/specflow-docs/src/embeddings/embedding-providers.ts`

### Agent workflow

- [Agent adapters](https://github.com/dczerwinskipl/nevo-specflow/blob/main/packages/specflow/src/program.ts): `packages/specflow/src/program.ts`

### Other components

- **Repository owner**

## Connections

- Repository owner → SpecFlow CLI: runs commands (evidence: `README.md`)
- Repository owner → SpecFlow UI: uses (evidence: `README.md`)
- SpecFlow CLI → Engine access: opens engine (evidence: `packages/specflow/src/engine-at.ts`)
- SpecFlow CLI → Runtime server: starts runtime (evidence: `packages/specflow/src/program.ts`)
- SpecFlow CLI → Docs commands: registers commands (evidence: `packages/specflow/src/program.ts`)
- SpecFlow UI → Runtime server: uses served UI (evidence: `README.md`)
- Runtime server → Auth and sessions: serves sessions
- Runtime server → Specification overview: serves specifications
- Runtime server → Specification workspace: serves workspace
- Runtime server → Document reads: serves reads
- Runtime server → Document writes: serves writes
- Engine boundary → Project Home: resolves home (evidence: `packages/specflow-engine/src/application.ts`)
- Engine boundary → Workspace registry: verifies registration (evidence: `packages/specflow-engine/src/application.ts`)
- Workspace registry → Project Home: reads home (evidence: `packages/specflow-engine/src/project/workspace/registry/registry.ts`)
- Engine boundary → Git workspaces: manages worktrees
- Specification overview → Engine boundary: reads canonical specs (evidence: `packages/specflow-runtime/src/features/specs/overview/repository/engine-repository.ts`)
- Specification workspace → Engine boundary: reads canonical specs (evidence: `packages/specflow-runtime/src/features/specs/workspace/engine-repository.ts`)
- Document reads → Engine boundary: reads documents (evidence: `packages/specflow-runtime/src/features/documents/content/engine-source.ts`)
- Document writes → Engine boundary: applies changes (evidence: `packages/specflow-runtime/src/features/documents/write/engine-write-source.ts`)
- Auth and sessions → Engine boundary: tracks execution
- Engine boundary → Specs and Tasks: owns workflow
- Docs commands → Repository corpus: discovers content
- Docs commands → Semantic embeddings: supports semantic search
- Agent adapters → SpecFlow CLI: exposes adapters (evidence: `packages/specflow/src/program.ts`)
