# weewrr/meshforge architecture

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

- Interactive diagram: https://gitdiagram.com/weewrr/meshforge
- Repository: https://github.com/weewrr/meshforge

## Overview

MeshForge is a local-first Electron desktop application for building node workflows that turn images and prompts into 3D meshes. Users edit and run graphs, watch generation progress, preview results, then export meshes or add them to the scene. The renderer’s workflow engine calls the authenticated FastAPI backend, which schedules jobs and dispatches generator implementations. Separate product branches support workflow persistence, model and extension management, mesh processing, settings, diagnostics, and agent-assisted workflows. The README documents the main process boundaries; some backend and UI links are documented rather than verified from sampled implementation.

Main entry points: [`server/main.py`](https://github.com/weewrr/meshforge/blob/main/server/main.py) (FastAPI App), [`src/App.tsx`](https://github.com/weewrr/meshforge/blob/main/src/App.tsx) (Renderer App), [`src/stores/workflowRun/engine.ts`](https://github.com/weewrr/meshforge/blob/main/src/stores/workflowRun/engine.ts) (Run Engine), [`src/pages/GeneratePage.tsx`](https://github.com/weewrr/meshforge/blob/main/src/pages/GeneratePage.tsx) (Generate Page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop Shell"]
  node_app["Renderer App<br/>[App.tsx]"]
  node_electron["Electron Main<br/>[index.ts]"]
  node_preload["Preload Bridge<br/>[index.ts]"]
end

subgraph group_workflow["Workflow Authoring"]
  node_workflow_ui["Workflow Canvas<br/>[index.tsx]"]
  node_workflow_state[("Workflow Library<br/>[storage.ts]")]
  node_run_engine["Run Engine<br/>[engine.ts]"]
  node_engine_context["Engine Context<br/>[engine-context.ts]"]
  node_workflow_api["Workflow API<br/>[workflows.ts]"]
end

subgraph group_generation["Generation Runtime"]
  node_generate_ui["Generate Page<br/>[GeneratePage.tsx]"]
  node_viewer["3D Viewer<br/>[Viewer3D.tsx]"]
  node_api_client["API Client<br/>[http.ts]"]
end

subgraph group_management["Models And Settings"]
  node_model_ui["Models Page<br/>[ModelsPage.tsx]"]
  node_extension_routes["Extension Routes<br/>[extensions.py]"]
  node_model_routes["Model Routes<br/>[model.py]"]
  node_settings_ui["Settings Page<br/>[index.tsx]"]
  node_agent_routes["Agent Routes<br/>[agent.py]"]
  node_mcp_server["MCP Server<br/>[mcp_server.py]"]
end

subgraph group_backend["Backend Services"]
  node_api_main["FastAPI App<br/>[main.py]"]
  node_job_router["Generation Routes<br/>[generate.py]"]
  node_job_store[("Job Persistence<br/>[jobstore.py]")]
  node_generator_registry["Generator Registry<br/>[registry.py]"]
  node_generator_impl["Built-in Generators"]
  node_mesh_processing["Mesh Processing<br/>[process.py]"]
end

node_user(("Desktop User"))

node_user -->|"uses"| node_app
node_app -->|"routes to"| node_workflow_ui
node_app -->|"routes to"| node_generate_ui
node_app -->|"routes to"| node_model_ui
node_app -->|"routes to"| node_settings_ui
node_workflow_ui -.->|"edits"| node_workflow_state
node_workflow_ui -.->|"starts run"| node_run_engine
node_run_engine -->|"shares context"| node_engine_context
node_run_engine -->|"polls jobs"| node_api_client
node_run_engine -.->|"runs workflows"| node_workflow_api
node_run_engine -.->|"returns progress"| node_generate_ui
node_generate_ui -.->|"previews mesh"| node_viewer
node_generate_ui -->|"requests services"| node_api_client
node_electron -->|"exposes IPC"| node_preload
node_electron -->|"spawns backend"| node_api_main
node_api_client -->|"sends requests"| node_api_main
node_api_main -->|"registers routes"| node_job_router
node_api_main -->|"registers routes"| node_extension_routes
node_api_main -->|"registers routes"| node_model_routes
node_api_main -->|"registers routes"| node_agent_routes
node_job_router -.->|"queues jobs"| node_job_store
node_job_router -.->|"dispatches generation"| node_generator_registry
node_generator_registry -->|"registers generators"| node_generator_impl
node_model_ui -.->|"manages extensions"| node_extension_routes
node_model_ui -.->|"manages models"| node_model_routes
node_generate_ui -->|"processes meshes"| node_mesh_processing
node_settings_ui -->|"reads runtime info"| node_api_client
node_mcp_server -->|"uses local API"| node_api_main

click node_app "https://github.com/weewrr/meshforge/blob/main/src/App.tsx"
click node_electron "https://github.com/weewrr/meshforge/blob/main/electron/main/index.ts"
click node_preload "https://github.com/weewrr/meshforge/blob/main/electron/preload/index.ts"
click node_workflow_ui "https://github.com/weewrr/meshforge/blob/main/src/pages/workflows/canvas/index.tsx"
click node_workflow_state "https://github.com/weewrr/meshforge/blob/main/src/stores/workflows/storage.ts"
click node_run_engine "https://github.com/weewrr/meshforge/blob/main/src/stores/workflowRun/engine.ts"
click node_engine_context "https://github.com/weewrr/meshforge/blob/main/src/stores/workflowRun/engine-context.ts"
click node_workflow_api "https://github.com/weewrr/meshforge/blob/main/src/api/workflows.ts"
click node_generate_ui "https://github.com/weewrr/meshforge/blob/main/src/pages/GeneratePage.tsx"
click node_viewer "https://github.com/weewrr/meshforge/blob/main/src/components/Viewer3D.tsx"
click node_api_client "https://github.com/weewrr/meshforge/blob/main/src/api/http.ts"
click node_api_main "https://github.com/weewrr/meshforge/blob/main/server/main.py"
click node_job_router "https://github.com/weewrr/meshforge/blob/main/server/routers/generate.py"
click node_job_store "https://github.com/weewrr/meshforge/blob/main/server/jobstore.py"
click node_generator_registry "https://github.com/weewrr/meshforge/blob/main/server/generators/registry.py"
click node_generator_impl "https://github.com/weewrr/meshforge/tree/main/server/generators"
click node_mesh_processing "https://github.com/weewrr/meshforge/blob/main/server/routers/process.py"
click node_model_ui "https://github.com/weewrr/meshforge/blob/main/src/pages/ModelsPage.tsx"
click node_extension_routes "https://github.com/weewrr/meshforge/blob/main/server/routers/extensions.py"
click node_model_routes "https://github.com/weewrr/meshforge/blob/main/server/routers/model.py"
click node_settings_ui "https://github.com/weewrr/meshforge/blob/main/src/pages/settings/index.tsx"
click node_agent_routes "https://github.com/weewrr/meshforge/blob/main/server/routers/agent.py"
click node_mcp_server "https://github.com/weewrr/meshforge/blob/main/server/mcp_server.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_app,node_electron,node_preload,node_user toneBlue
class node_workflow_ui,node_workflow_state,node_run_engine,node_engine_context,node_workflow_api toneAmber
class node_generate_ui,node_viewer,node_api_client toneMint
class node_model_ui,node_extension_routes,node_model_routes,node_settings_ui,node_agent_routes,node_mcp_server toneRose
class node_api_main,node_job_router,node_job_store,node_generator_registry,node_generator_impl,node_mesh_processing toneIndigo
```

## Components

### Desktop Shell

- [Renderer App](https://github.com/weewrr/meshforge/blob/main/src/App.tsx): `src/App.tsx`
- [Electron Main](https://github.com/weewrr/meshforge/blob/main/electron/main/index.ts): `electron/main/index.ts`
- [Preload Bridge](https://github.com/weewrr/meshforge/blob/main/electron/preload/index.ts): `electron/preload/index.ts`

### Workflow Authoring

- [Workflow Canvas](https://github.com/weewrr/meshforge/blob/main/src/pages/workflows/canvas/index.tsx): `src/pages/workflows/canvas/index.tsx`
- [Workflow Library](https://github.com/weewrr/meshforge/blob/main/src/stores/workflows/storage.ts): `src/stores/workflows/storage.ts`
- [Run Engine](https://github.com/weewrr/meshforge/blob/main/src/stores/workflowRun/engine.ts): `src/stores/workflowRun/engine.ts`
- [Engine Context](https://github.com/weewrr/meshforge/blob/main/src/stores/workflowRun/engine-context.ts): `src/stores/workflowRun/engine-context.ts`
- [Workflow API](https://github.com/weewrr/meshforge/blob/main/src/api/workflows.ts): `src/api/workflows.ts`

### Generation Runtime

- [Generate Page](https://github.com/weewrr/meshforge/blob/main/src/pages/GeneratePage.tsx): `src/pages/GeneratePage.tsx`
- [3D Viewer](https://github.com/weewrr/meshforge/blob/main/src/components/Viewer3D.tsx): `src/components/Viewer3D.tsx`
- [API Client](https://github.com/weewrr/meshforge/blob/main/src/api/http.ts): `src/api/http.ts`

### Models And Settings

- [Models Page](https://github.com/weewrr/meshforge/blob/main/src/pages/ModelsPage.tsx): `src/pages/ModelsPage.tsx`
- [Extension Routes](https://github.com/weewrr/meshforge/blob/main/server/routers/extensions.py): `server/routers/extensions.py`
- [Model Routes](https://github.com/weewrr/meshforge/blob/main/server/routers/model.py): `server/routers/model.py`
- [Settings Page](https://github.com/weewrr/meshforge/blob/main/src/pages/settings/index.tsx): `src/pages/settings/index.tsx`
- [Agent Routes](https://github.com/weewrr/meshforge/blob/main/server/routers/agent.py): `server/routers/agent.py`
- [MCP Server](https://github.com/weewrr/meshforge/blob/main/server/mcp_server.py): `server/mcp_server.py`

### Backend Services

- [FastAPI App](https://github.com/weewrr/meshforge/blob/main/server/main.py): `server/main.py`
- [Generation Routes](https://github.com/weewrr/meshforge/blob/main/server/routers/generate.py): `server/routers/generate.py`
- [Job Persistence](https://github.com/weewrr/meshforge/blob/main/server/jobstore.py): `server/jobstore.py`
- [Generator Registry](https://github.com/weewrr/meshforge/blob/main/server/generators/registry.py): `server/generators/registry.py`
- [Built-in Generators](https://github.com/weewrr/meshforge/tree/main/server/generators): `server/generators`
- [Mesh Processing](https://github.com/weewrr/meshforge/blob/main/server/routers/process.py): `server/routers/process.py`

### Other components

- **Desktop User**

## Connections

- Desktop User → Renderer App: uses
- Renderer App → Workflow Canvas: routes to (evidence: `src/App.tsx`)
- Renderer App → Generate Page: routes to (evidence: `src/App.tsx`)
- Renderer App → Models Page: routes to (evidence: `src/App.tsx`)
- Renderer App → Settings Page: routes to (evidence: `src/App.tsx`)
- Workflow Canvas → Workflow Library: edits
- Workflow Canvas → Run Engine: starts run
- Run Engine → Engine Context: shares context (evidence: `src/stores/workflowRun/engine.ts`)
- Run Engine → API Client: polls jobs (evidence: `src/stores/workflowRun/engine.ts`)
- Run Engine → Workflow API: runs workflows
- Run Engine → Generate Page: returns progress
- Generate Page → 3D Viewer: previews mesh
- Generate Page → API Client: requests services
- Electron Main → Preload Bridge: exposes IPC (evidence: `electron/main/index.ts`)
- Electron Main → FastAPI App: spawns backend
- API Client → FastAPI App: sends requests
- FastAPI App → Generation Routes: registers routes (evidence: `server/main.py`)
- FastAPI App → Extension Routes: registers routes (evidence: `server/main.py`)
- FastAPI App → Model Routes: registers routes (evidence: `server/main.py`)
- FastAPI App → Agent Routes: registers routes (evidence: `server/main.py`)
- Generation Routes → Job Persistence: queues jobs
- Generation Routes → Generator Registry: dispatches generation
- Generator Registry → Built-in Generators: registers generators (evidence: `server/generators/registry.py`)
- Models Page → Extension Routes: manages extensions
- Models Page → Model Routes: manages models
- Generate Page → Mesh Processing: processes meshes
- Settings Page → API Client: reads runtime info
- MCP Server → FastAPI App: uses local API
