# coryhacking/wavefoundry architecture

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

- Interactive diagram: https://gitdiagram.com/coryhacking/wavefoundry
- Repository: https://github.com/coryhacking/wavefoundry

## Overview

Wavefoundry is a spec-driven development framework for AI coding agents, combining a local MCP tool server with repository indexing and workflow support. The documented setup flow bootstraps the framework, builds a project index, configures the agent host, and hands control back after an MCP restart. The README excerpt establishes setup and indexing relationships; internal links among lifecycle, memory, and retrieval modules are not shown, so they are omitted rather than inferred.

Main entry points: [`.wavefoundry/framework/scripts/setup_wavefoundry.py`](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/setup_wavefoundry.py) (Setup Orchestrator), [`.wavefoundry/framework/scripts/indexer.py`](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/indexer.py) (Project Index), [`.wavefoundry/framework/scripts/server.py`](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/server.py) (MCP Server), [`.mcp.json`](https://github.com/coryhacking/wavefoundry/blob/main/.mcp.json) (Host Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Setup and Host"]
  node_setup_flow["Setup Orchestrator"]
  node_host_config["Host Configuration<br/>[.mcp.json]"]
  node_launchers["WF Launchers<br/>[wf]"]
end

subgraph group_indexing["Repository Intelligence"]
  node_project_index["Project Index<br/>[indexer.py]"]
  node_code_graph["Code Graph<br/>[graph_indexer.py]"]
  node_vector_store[("Vector Store")]
end

subgraph group_workflow["Engineering Workflow"]
  node_lifecycle["Workflow Lifecycle<br/>[skills]"]
  node_memory["Project Memory<br/>[memory_cli.py]"]
  node_techdocs["Techdocs Support<br/>[techdocs_audit.py]"]
end

subgraph group_interfaces["Agent Interfaces"]
  node_mcp_server["MCP Server<br/>[server.py]"]
  node_mcp_extensions["MCP Tools"]
  node_dashboard["Workflow Dashboard<br/>[dashboard.js]"]
end

node_engineer(("Engineer"))
node_coding_agent(("Coding Agent"))

node_engineer -->|"requests setup"| node_coding_agent
node_coding_agent -->|"runs setup"| node_setup_flow
node_setup_flow -->|"builds index"| node_project_index
node_setup_flow -->|"writes config"| node_host_config
node_setup_flow -->|"writes launchers"| node_launchers
node_setup_flow -->|"dry-runs server"| node_mcp_server
node_coding_agent -.->|"uses tools"| node_mcp_server
node_project_index -.->|"indexes code"| node_code_graph
node_project_index -.->|"stores embeddings"| node_vector_store
node_mcp_server -.->|"dispatches tools"| node_mcp_extensions

click node_setup_flow "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/setup_wavefoundry.py"
click node_host_config "https://github.com/coryhacking/wavefoundry/blob/main/.mcp.json"
click node_launchers "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/bin/wf"
click node_project_index "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/indexer.py"
click node_code_graph "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/graph_indexer.py"
click node_vector_store "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/sqlite_vector_store.py"
click node_mcp_server "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/server.py"
click node_mcp_extensions "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/mcp_tool_extensions.py"
click node_lifecycle "https://github.com/coryhacking/wavefoundry/tree/main/.agents/skills"
click node_memory "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/memory_cli.py"
click node_dashboard "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/dashboard/dashboard.js"
click node_techdocs "https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/techdocs_audit.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_setup_flow,node_host_config,node_launchers toneBlue
class node_project_index,node_code_graph,node_vector_store toneAmber
class node_lifecycle,node_memory,node_techdocs toneMint
class node_mcp_server,node_mcp_extensions,node_dashboard toneRose
class node_engineer,node_coding_agent toneIndigo
```

## Components

### Setup and Host

- [Setup Orchestrator](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/setup_wavefoundry.py): `.wavefoundry/framework/scripts/setup_wavefoundry.py`
- [Host Configuration](https://github.com/coryhacking/wavefoundry/blob/main/.mcp.json): `.mcp.json`
- [WF Launchers](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/bin/wf): `.wavefoundry/bin/wf`

### Repository Intelligence

- [Project Index](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/indexer.py): `.wavefoundry/framework/scripts/indexer.py`
- [Code Graph](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/graph_indexer.py): `.wavefoundry/framework/scripts/graph_indexer.py`
- [Vector Store](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/sqlite_vector_store.py): `.wavefoundry/framework/scripts/sqlite_vector_store.py`

### Engineering Workflow

- [Workflow Lifecycle](https://github.com/coryhacking/wavefoundry/tree/main/.agents/skills): `.agents/skills`
- [Project Memory](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/memory_cli.py): `.wavefoundry/framework/scripts/memory_cli.py`
- [Techdocs Support](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/techdocs_audit.py): `.wavefoundry/framework/scripts/techdocs_audit.py`

### Agent Interfaces

- [MCP Server](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/server.py): `.wavefoundry/framework/scripts/server.py`
- [MCP Tools](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/scripts/mcp_tool_extensions.py): `.wavefoundry/framework/scripts/mcp_tool_extensions.py`
- [Workflow Dashboard](https://github.com/coryhacking/wavefoundry/blob/main/.wavefoundry/framework/dashboard/dashboard.js): `.wavefoundry/framework/dashboard/dashboard.js`

### Other components

- **Engineer**
- **Coding Agent**

## Connections

- Engineer → Coding Agent: requests setup (evidence: `README.md`)
- Coding Agent → Setup Orchestrator: runs setup (evidence: `README.md`)
- Setup Orchestrator → Project Index: builds index (evidence: `README.md`)
- Setup Orchestrator → Host Configuration: writes config (evidence: `README.md`)
- Setup Orchestrator → WF Launchers: writes launchers (evidence: `README.md`)
- Setup Orchestrator → MCP Server: dry-runs server (evidence: `README.md`)
- Coding Agent → MCP Server: uses tools
- Project Index → Code Graph: indexes code
- Project Index → Vector Store: stores embeddings
- MCP Server → MCP Tools: dispatches tools
