# nwave-ai/nwave-experimental architecture

> Architecture diagram of the GitHub repository nwave-ai/nwave-experimental, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nwave-ai/nwave-experimental
- Repository: https://github.com/nwave-ai/nwave-experimental
- Video tour (about a minute): https://gitdiagram.com/nwave-ai/nwave-experimental/video

## Overview

nWave’s DES runtime guides an assistant through delivering a request in explicit steps, with the assistant deciding when to continue. The documented path establishes a goal and design, defines an executable public oracle, implements and reviews the change, examines behavior without reading implementation, then integrates it. The graph also shows host hooks and the task-invocation boundary as supporting capabilities. Workflow ordering comes from the README; source excerpts were partial, so internal wiring beyond those documented relationships is omitted.

Main entry points: [`lib/python/des/cli/craft.py`](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/craft.py) (Define goal), [`lib/python/des/cli/design.py`](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/design.py) (Establish design), [`lib/python/des/cli/oracle.py`](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/oracle.py) (Define oracle), [`lib/python/des/cli/invoke_role.py`](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/invoke_role.py) (Implement change)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Request delivery"]
  node_goal["Define goal<br/>[craft.py]"]
  node_design["Establish design<br/>[design.py]"]
  node_oracle["Define oracle<br/>[oracle.py]"]
  node_implement["Implement change<br/>[invoke_role.py]"]
  node_review["Review change<br/>[verify.py]"]
  node_observe["Observe behavior"]
  node_integrate["Integrate result<br/>[integrate.py]"]
end

subgraph group_interfaces["User interfaces"]
  node_po["Start delivery<br/>[po.py]"]
  node_state["Request state<br/>[state.py]"]
end

subgraph group_runtime["Execution boundary"]
  node_progress["Step progression<br/>[delivery_steps.py]"]
  node_continuation["Continuation logic"]
  node_task["Task adapters"]
  node_git["Git operations<br/>[git_mutate.py]"]
end

subgraph group_host["Host integration"]
  node_hook["Host hooks<br/>[hook_router.py]"]
  node_session["Session notice"]
end

node_assistant(("Assistant"))

node_assistant -->|"starts request"| node_po
node_assistant -->|"checks status"| node_state
node_po -->|"begins delivery"| node_goal
node_goal -->|"next step"| node_design
node_design -->|"next step"| node_oracle
node_oracle -->|"next step"| node_implement
node_implement -->|"next step"| node_review
node_review -->|"next step"| node_observe
node_observe -->|"next step"| node_integrate
node_assistant -->|"chooses next"| node_progress
node_progress -->|"advances state"| node_continuation
node_hook -->|"routes session"| node_session
node_assistant -.->|"host events"| node_hook

click node_po "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/po.py"
click node_state "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/state.py"
click node_goal "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/craft.py"
click node_design "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/design.py"
click node_oracle "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/oracle.py"
click node_implement "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/invoke_role.py"
click node_review "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/verify.py"
click node_observe "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/verify_red_green.py"
click node_integrate "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/integrate.py"
click node_progress "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/application/delivery_steps.py"
click node_continuation "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/application/delivery_continuation.py"
click node_task "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/adapters/driven/task_invocation/configured_task_adapter.py"
click node_git "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/adapters/driven/git/git_mutate.py"
click node_hook "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/adapters/drivers/hooks/hook_router.py"
click node_session "https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/adapters/drivers/hooks/session_start_notice_handler.py"

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_goal,node_design,node_oracle,node_implement,node_review,node_observe,node_integrate toneBlue
class node_po,node_state toneAmber
class node_progress,node_continuation,node_task,node_git toneMint
class node_hook,node_session toneRose
class node_assistant toneIndigo
```

## Components

### Request delivery

- [Define goal](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/craft.py): `lib/python/des/cli/craft.py`
- [Establish design](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/design.py): `lib/python/des/cli/design.py`
- [Define oracle](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/oracle.py): `lib/python/des/cli/oracle.py`
- [Implement change](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/invoke_role.py): `lib/python/des/cli/invoke_role.py`
- [Review change](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/verify.py): `lib/python/des/cli/verify.py`
- [Observe behavior](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/verify_red_green.py): `lib/python/des/cli/verify_red_green.py`
- [Integrate result](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/integrate.py): `lib/python/des/cli/integrate.py`

### User interfaces

- [Start delivery](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/po.py): `lib/python/des/cli/po.py`
- [Request state](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/cli/state.py): `lib/python/des/cli/state.py`

### Execution boundary

- [Step progression](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/application/delivery_steps.py): `lib/python/des/application/delivery_steps.py`
- [Continuation logic](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/application/delivery_continuation.py): `lib/python/des/application/delivery_continuation.py`
- [Task adapters](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/adapters/driven/task_invocation/configured_task_adapter.py): `lib/python/des/adapters/driven/task_invocation/configured_task_adapter.py`
- [Git operations](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/adapters/driven/git/git_mutate.py): `lib/python/des/adapters/driven/git/git_mutate.py`

### Host integration

- [Host hooks](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/adapters/drivers/hooks/hook_router.py): `lib/python/des/adapters/drivers/hooks/hook_router.py`
- [Session notice](https://github.com/nwave-ai/nwave-experimental/blob/main/lib/python/des/adapters/drivers/hooks/session_start_notice_handler.py): `lib/python/des/adapters/drivers/hooks/session_start_notice_handler.py`

### Other components

- **Assistant**

## Connections

- Assistant → Start delivery: starts request
- Assistant → Request state: checks status
- Start delivery → Define goal: begins delivery
- Define goal → Establish design: next step
- Establish design → Define oracle: next step
- Define oracle → Implement change: next step
- Implement change → Review change: next step
- Review change → Observe behavior: next step
- Observe behavior → Integrate result: next step
- Assistant → Step progression: chooses next
- Step progression → Continuation logic: advances state
- Host hooks → Session notice: routes session
- Assistant → Host hooks: host events