# saiakashneela/projectmesh architecture

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

- Interactive diagram: https://gitdiagram.com/saiakashneela/projectmesh
- Repository: https://github.com/saiakashneela/projectmesh

## Overview

Projectmesh is a local AI engineering platform for a repository-scoped Architect-to-Executor handoff. An AI client inspects a selected workspace and records tasks and project context through MCP; Projectmesh packages the active task and affected source for a locally approved executor, then records execution state and a review. The CLI also initializes and analyzes repositories, while a multi-workspace registry and optional HTTP/ngrok sharing support concurrent remote access. The graph follows documented capabilities where source excerpts are incomplete; uncertain internal wiring is omitted.

Main entry points: [`src/cli.ts`](https://github.com/saiakashneela/projectmesh/blob/main/src/cli.ts) (Projectmesh CLI), [`src/ai-workspace.ts`](https://github.com/saiakashneela/projectmesh/blob/main/src/ai-workspace.ts) (AI Workspace Flows), [`src/share.ts`](https://github.com/saiakashneela/projectmesh/blob/main/src/share.ts) (HTTP Sharing), [`src/mcp-tools.ts`](https://github.com/saiakashneela/projectmesh/blob/main/src/mcp-tools.ts) (Platform Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Access"]
  node_cli["Projectmesh CLI<br/>[cli.ts]"]
  node_mcp["MCP Server<br/>[mcp-server.ts]"]
  node_sharing["HTTP Sharing<br/>[share.ts]"]
  node_dashboard["Dashboard<br/>[dashboard.ts]"]
  node_tools["Platform Tools<br/>[mcp-tools.ts]"]
  node_ngrok["ngrok Tunnel"]
end

subgraph group_planning["Planning Handoff"]
  node_analysis["Repository Analysis"]
  node_aiworkspace["AI Workspace Flows<br/>[ai-workspace.ts]"]
  node_taskfiles["Task Context"]
  node_packet["Task Packet"]
end

subgraph group_execution["Execution Review"]
  node_executorrunner["Agent Runners<br/>[agent-runners.ts]"]
  node_executionstate["Execution Records"]
end

subgraph group_platform["Workspace Platform"]
  node_workspace["Workspace Access<br/>[workspace.ts]"]
  node_registry["Workspace Registry<br/>[platform-config.ts]"]
  node_git["Git Operations<br/>[git.ts]"]
  node_repo["Target Repository"]
  node_platformstate[("Platform State")]
end

node_architect(("Architect AI"))
node_user(("Local User"))
node_executor(("Executor Agent"))

node_user -->|"runs commands"| node_cli
node_architect -->|"connects tools"| node_mcp
node_mcp -->|"dispatches tools"| node_tools
node_mcp -->|"resolves workspaces"| node_registry
node_tools -->|"requests inspection"| node_analysis
node_tools -->|"manages handoff"| node_aiworkspace
node_tools -->|"runs git tools"| node_git
node_analysis -->|"reads workspace"| node_workspace
node_analysis -->|"inspects files"| node_repo
node_aiworkspace -->|"reads and writes"| node_workspace
node_aiworkspace -->|"updates tasks"| node_taskfiles
node_aiworkspace -->|"generates packet"| node_packet
node_cli -->|"analyzes repository"| node_analysis
node_cli -->|"runs handoff flows"| node_aiworkspace
node_cli -->|"selects workspace"| node_registry
node_cli -->|"starts services"| node_sharing
node_cli -->|"selects executor"| node_executorrunner
node_cli -->|"captures changes"| node_git
node_user -->|"approves execution"| node_cli
node_cli -->|"records execution"| node_executionstate
node_executorrunner -->|"launches agent"| node_executor
node_executor -->|"changes files"| node_repo
node_cli -->|"writes report"| node_aiworkspace
node_sharing -->|"serves HTTP MCP"| node_mcp
node_sharing -->|"starts dashboard"| node_dashboard
node_sharing -.->|"starts tunnel"| node_ngrok
node_dashboard -->|"reads workspace state"| node_registry
node_dashboard -.->|"configures token"| node_ngrok
node_registry -->|"reads and writes"| node_platformstate
node_git -->|"reads git state"| node_repo
node_workspace -->|"confines file access"| node_repo

click node_cli "https://github.com/saiakashneela/projectmesh/blob/main/src/cli.ts"
click node_mcp "https://github.com/saiakashneela/projectmesh/blob/main/src/mcp-server.ts"
click node_sharing "https://github.com/saiakashneela/projectmesh/blob/main/src/share.ts"
click node_dashboard "https://github.com/saiakashneela/projectmesh/blob/main/src/dashboard.ts"
click node_tools "https://github.com/saiakashneela/projectmesh/blob/main/src/mcp-tools.ts"
click node_analysis "https://github.com/saiakashneela/projectmesh/blob/main/src/repository-analysis.ts"
click node_aiworkspace "https://github.com/saiakashneela/projectmesh/blob/main/src/ai-workspace.ts"
click node_workspace "https://github.com/saiakashneela/projectmesh/blob/main/src/workspace.ts"
click node_registry "https://github.com/saiakashneela/projectmesh/blob/main/src/platform-config.ts"
click node_git "https://github.com/saiakashneela/projectmesh/blob/main/src/git.ts"
click node_executorrunner "https://github.com/saiakashneela/projectmesh/blob/main/src/agent-runners.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_mcp,node_sharing,node_dashboard,node_tools,node_ngrok,node_user toneBlue
class node_analysis,node_aiworkspace,node_taskfiles,node_packet toneAmber
class node_executorrunner,node_executionstate toneMint
class node_workspace,node_registry,node_git,node_repo,node_platformstate toneRose
class node_architect,node_executor toneIndigo
```

## Components

### User Access

- [Projectmesh CLI](https://github.com/saiakashneela/projectmesh/blob/main/src/cli.ts): `src/cli.ts`
- [MCP Server](https://github.com/saiakashneela/projectmesh/blob/main/src/mcp-server.ts): `src/mcp-server.ts`
- [HTTP Sharing](https://github.com/saiakashneela/projectmesh/blob/main/src/share.ts): `src/share.ts`
- [Dashboard](https://github.com/saiakashneela/projectmesh/blob/main/src/dashboard.ts): `src/dashboard.ts`
- [Platform Tools](https://github.com/saiakashneela/projectmesh/blob/main/src/mcp-tools.ts): `src/mcp-tools.ts`
- **ngrok Tunnel**

### Planning Handoff

- [Repository Analysis](https://github.com/saiakashneela/projectmesh/blob/main/src/repository-analysis.ts): `src/repository-analysis.ts`
- [AI Workspace Flows](https://github.com/saiakashneela/projectmesh/blob/main/src/ai-workspace.ts): `src/ai-workspace.ts`
- **Task Context**
- **Task Packet**

### Execution Review

- [Agent Runners](https://github.com/saiakashneela/projectmesh/blob/main/src/agent-runners.ts): `src/agent-runners.ts`
- **Execution Records**

### Workspace Platform

- [Workspace Access](https://github.com/saiakashneela/projectmesh/blob/main/src/workspace.ts): `src/workspace.ts`
- [Workspace Registry](https://github.com/saiakashneela/projectmesh/blob/main/src/platform-config.ts): `src/platform-config.ts`
- [Git Operations](https://github.com/saiakashneela/projectmesh/blob/main/src/git.ts): `src/git.ts`
- **Target Repository**
- **Platform State**

### Other components

- **Architect AI**
- **Local User**
- **Executor Agent**

## Connections

- Local User → Projectmesh CLI: runs commands
- Architect AI → MCP Server: connects tools
- MCP Server → Platform Tools: dispatches tools
- MCP Server → Workspace Registry: resolves workspaces
- Platform Tools → Repository Analysis: requests inspection
- Platform Tools → AI Workspace Flows: manages handoff
- Platform Tools → Git Operations: runs git tools
- Repository Analysis → Workspace Access: reads workspace
- Repository Analysis → Target Repository: inspects files
- AI Workspace Flows → Workspace Access: reads and writes
- AI Workspace Flows → Task Context: updates tasks
- AI Workspace Flows → Task Packet: generates packet
- Projectmesh CLI → Repository Analysis: analyzes repository
- Projectmesh CLI → AI Workspace Flows: runs handoff flows
- Projectmesh CLI → Workspace Registry: selects workspace
- Projectmesh CLI → HTTP Sharing: starts services
- Projectmesh CLI → Agent Runners: selects executor
- Projectmesh CLI → Git Operations: captures changes
- Local User → Projectmesh CLI: approves execution
- Projectmesh CLI → Execution Records: records execution
- Agent Runners → Executor Agent: launches agent
- Executor Agent → Target Repository: changes files
- Projectmesh CLI → AI Workspace Flows: writes report
- HTTP Sharing → MCP Server: serves HTTP MCP
- HTTP Sharing → Dashboard: starts dashboard
- HTTP Sharing → ngrok Tunnel: starts tunnel
- Dashboard → Workspace Registry: reads workspace state
- Dashboard → ngrok Tunnel: configures token
- Workspace Registry → Platform State: reads and writes
- Git Operations → Target Repository: reads git state
- Workspace Access → Target Repository: confines file access