# thu-maic/openmaic-project architecture

> Architecture diagram of the GitHub repository thu-maic/openmaic-project, 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/thu-maic/openmaic-project
- Repository: https://github.com/thu-maic/openmaic-project

## Overview

OpenMAIC-Project is an Electron desktop environment for project-based learning. A learner configures the local app, submits a project brief, reviews a generated plan, then works with role-based AI collaborators in a sandboxed workspace using chat, documents, files, code, terminal, and browser tools. The endpoint separates planner sessions from learning-phase sessions and exposes project design and workspace APIs. The README documents the lifecycle and major capabilities; source excerpts and the index establish selected runtime links, but do not expose all UI-to-API wiring.

Main entry points: [`endpoint/service/project_planner/session.py`](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/project_planner/session.py) (Planner session), [`src/renderer/App.tsx`](https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/App.tsx) (App routing), [`endpoint/service/workspace/collaborator/session.py`](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/collaborator/session.py) (Collaborator sessions), [`endpoint/service/workspace/instructor/session.py`](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/instructor/session.py) (Instructor session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop client"]
  node_electron["Electron main<br/>[main.ts]"]
  node_endpoint_mgr["Endpoint manager"]
  node_app["App routing<br/>[App.tsx]"]
  node_setup["Setup wizard<br/>[InfraStep.tsx]"]
  node_planner_ui["Planner UI<br/>[StartPage.tsx]"]
  node_review_ui["Plan review<br/>[ReviewPage.tsx]"]
  node_workspace_ui["Workspace shell<br/>[WorkspaceShell.tsx]"]
  node_workspace_tools_ui["Workspace tools<br/>[WorkArea.tsx]"]
end

subgraph group_endpoint["Local endpoint"]
  node_api["FastAPI routes<br/>[main.py]"]
end

subgraph group_planning["Project planning"]
  node_planner_api["Planner routes<br/>[project_planner.py]"]
  node_planner_session["Planner session<br/>[session.py]"]
  node_planner_agent["Planner agent<br/>[agent.py]"]
end

subgraph group_learning["Learning workspace"]
  node_collaborator["Collaborator sessions<br/>[session.py]"]
  node_instructor["Instructor session<br/>[session.py]"]
  node_simulator["Scene actor sessions<br/>[session.py]"]
  node_container["Workspace container<br/>[container.py]"]
  node_integrations["Shared documents<br/>[integrations.py]"]
end

subgraph group_design["Project design"]
  node_project_meta["Project metadata<br/>[project.py]"]
  node_roles["Role definitions<br/>[roles.py]"]
  node_issueboard["Milestones and tasks<br/>[issueboard.py]"]
  node_project_auth["Agent authorization<br/>[auth.py]"]
end

node_learner(("Learner"))
node_llm{{"LLM provider"}}
node_sandbox["Docker sandbox"]

node_learner -->|"uses"| node_app
node_electron -->|"starts endpoint"| node_endpoint_mgr
node_endpoint_mgr -->|"launches"| node_api
node_app -->|"routes setup"| node_setup
node_app -->|"routes brief"| node_planner_ui
node_app -->|"routes review"| node_review_ui
node_app -->|"routes workspace"| node_workspace_ui
node_workspace_ui -.->|"renders tools"| node_workspace_tools_ui
node_api -->|"registers routes"| node_planner_api
node_planner_api -->|"delegates"| node_planner_session
node_planner_session -->|"runs agent"| node_planner_agent
node_planner_session -->|"reads project"| node_project_meta
node_planner_session -->|"uses role design"| node_roles
node_planner_session -->|"uses issueboard"| node_issueboard
node_planner_session -.->|"requests reasoning"| node_llm
node_planner_session -.->|"returns plan"| node_review_ui
node_collaborator -->|"starts container"| node_container
node_simulator -->|"starts container"| node_container
node_instructor -->|"consults sessions"| node_collaborator
node_collaborator -->|"uses documents"| node_integrations
node_instructor -->|"uses documents"| node_integrations
node_collaborator -.->|"runs collaborator"| node_llm
node_instructor -.->|"runs instructor"| node_llm
node_simulator -.->|"runs scene actor"| node_llm
node_container -->|"manages"| node_sandbox
node_workspace_ui -.->|"uses sessions"| node_collaborator
node_planner_ui -.->|"submits brief"| node_planner_api
node_review_ui -.->|"reviews design"| node_project_meta

click node_electron "https://github.com/thu-maic/openmaic-project/blob/main/src/main/main.ts"
click node_endpoint_mgr "https://github.com/thu-maic/openmaic-project/blob/main/src/main/endpoint-manager.ts"
click node_app "https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/App.tsx"
click node_setup "https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/setup/steps/InfraStep.tsx"
click node_planner_ui "https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/project/StartPage.tsx"
click node_review_ui "https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/project/ReviewPage.tsx"
click node_workspace_ui "https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/workspace/WorkspaceShell.tsx"
click node_workspace_tools_ui "https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/workspace/components/WorkArea.tsx"
click node_api "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/main.py"
click node_planner_api "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_planner.py"
click node_planner_session "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/project_planner/session.py"
click node_planner_agent "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/project_planner/agent.py"
click node_project_meta "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_design/project.py"
click node_roles "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_design/roles.py"
click node_issueboard "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_design/issueboard.py"
click node_project_auth "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_design/auth.py"
click node_collaborator "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/collaborator/session.py"
click node_instructor "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/instructor/session.py"
click node_simulator "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/simulator/session.py"
click node_container "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/container.py"
click node_integrations "https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/integrations.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_electron,node_endpoint_mgr,node_app,node_setup,node_planner_ui,node_review_ui,node_workspace_ui,node_workspace_tools_ui toneBlue
class node_api toneAmber
class node_planner_api,node_planner_session,node_planner_agent toneMint
class node_collaborator,node_instructor,node_simulator,node_container,node_integrations toneRose
class node_project_meta,node_roles,node_issueboard,node_project_auth,node_learner,node_llm,node_sandbox toneIndigo
```

## Components

### Desktop client

- [Electron main](https://github.com/thu-maic/openmaic-project/blob/main/src/main/main.ts): `src/main/main.ts`
- [Endpoint manager](https://github.com/thu-maic/openmaic-project/blob/main/src/main/endpoint-manager.ts): `src/main/endpoint-manager.ts`
- [App routing](https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/App.tsx): `src/renderer/App.tsx`
- [Setup wizard](https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/setup/steps/InfraStep.tsx): `src/renderer/pages/setup/steps/InfraStep.tsx`
- [Planner UI](https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/project/StartPage.tsx): `src/renderer/pages/project/StartPage.tsx`
- [Plan review](https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/project/ReviewPage.tsx): `src/renderer/pages/project/ReviewPage.tsx`
- [Workspace shell](https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/workspace/WorkspaceShell.tsx): `src/renderer/pages/workspace/WorkspaceShell.tsx`
- [Workspace tools](https://github.com/thu-maic/openmaic-project/blob/main/src/renderer/pages/workspace/components/WorkArea.tsx): `src/renderer/pages/workspace/components/WorkArea.tsx`

### Local endpoint

- [FastAPI routes](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/main.py): `endpoint/main.py`

### Project planning

- [Planner routes](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_planner.py): `endpoint/api/project_planner.py`
- [Planner session](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/project_planner/session.py): `endpoint/service/project_planner/session.py`
- [Planner agent](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/project_planner/agent.py): `endpoint/service/project_planner/agent.py`

### Learning workspace

- [Collaborator sessions](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/collaborator/session.py): `endpoint/service/workspace/collaborator/session.py`
- [Instructor session](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/instructor/session.py): `endpoint/service/workspace/instructor/session.py`
- [Scene actor sessions](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/simulator/session.py): `endpoint/service/workspace/simulator/session.py`
- [Workspace container](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/service/workspace/container.py): `endpoint/service/workspace/container.py`
- [Shared documents](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/integrations.py): `endpoint/api/integrations.py`

### Project design

- [Project metadata](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_design/project.py): `endpoint/api/project_design/project.py`
- [Role definitions](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_design/roles.py): `endpoint/api/project_design/roles.py`
- [Milestones and tasks](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_design/issueboard.py): `endpoint/api/project_design/issueboard.py`
- [Agent authorization](https://github.com/thu-maic/openmaic-project/blob/main/endpoint/api/project_design/auth.py): `endpoint/api/project_design/auth.py`

### Other components

- **Learner**
- **LLM provider**
- **Docker sandbox**

## Connections

- Learner → App routing: uses (evidence: `README.md`)
- Electron main → Endpoint manager: starts endpoint (evidence: `src/main/main.ts`)
- Endpoint manager → FastAPI routes: launches (evidence: `src/main/endpoint-manager.ts`)
- App routing → Setup wizard: routes setup (evidence: `src/renderer/App.tsx`)
- App routing → Planner UI: routes brief (evidence: `src/renderer/App.tsx`)
- App routing → Plan review: routes review (evidence: `src/renderer/App.tsx`)
- App routing → Workspace shell: routes workspace (evidence: `src/renderer/App.tsx`)
- Workspace shell → Workspace tools: renders tools
- FastAPI routes → Planner routes: registers routes (evidence: `endpoint/main.py`)
- Planner routes → Planner session: delegates (evidence: `endpoint/service/project_planner/session.py`)
- Planner session → Planner agent: runs agent (evidence: `endpoint/service/project_planner/session.py`)
- Planner session → Project metadata: reads project (evidence: `endpoint/service/project_planner/session.py`)
- Planner session → Role definitions: uses role design (evidence: `endpoint/service/project_planner/session.py`)
- Planner session → Milestones and tasks: uses issueboard (evidence: `endpoint/service/project_planner/session.py`)
- Planner session → LLM provider: requests reasoning
- Planner session → Plan review: returns plan
- Collaborator sessions → Workspace container: starts container (evidence: `endpoint/service/workspace/collaborator/session.py`)
- Scene actor sessions → Workspace container: starts container (evidence: `endpoint/service/workspace/simulator/session.py`)
- Instructor session → Collaborator sessions: consults sessions (evidence: `endpoint/service/workspace/instructor/session.py`)
- Collaborator sessions → Shared documents: uses documents (evidence: `endpoint/service/workspace/collaborator/session.py`)
- Instructor session → Shared documents: uses documents (evidence: `endpoint/service/workspace/instructor/session.py`)
- Collaborator sessions → LLM provider: runs collaborator
- Instructor session → LLM provider: runs instructor
- Scene actor sessions → LLM provider: runs scene actor
- Workspace container → Docker sandbox: manages (evidence: `README.md`)
- Workspace shell → Collaborator sessions: uses sessions
- Planner UI → Planner routes: submits brief
- Plan review → Project metadata: reviews design
