# mrleepee/miroclaw architecture

> Architecture diagram of the GitHub repository mrleepee/miroclaw, 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/mrleepee/miroclaw
- Repository: https://github.com/mrleepee/miroclaw

## Overview

MiroClaw is a research-armed multi-agent forecasting product. A user supplies seed material, builds a knowledge graph, configures simulated agents, runs phased social simulations, receives calibrated forecasts and a report, then can chat with agents or the report agent. The graph separates the Vue workflow, Flask API, graph construction and storage, simulation execution, and analysis. README documents the product stages; sampled excerpts confirm the phased orchestrator, graph storage, browser research client, simulation preparation, and frontend history access. Some unsampled endpoint-to-service wiring is therefore left implicit.

Main entry points: [`frontend/src/api`](https://github.com/mrleepee/miroclaw/tree/main/frontend/src/api) (API clients), [`frontend/src/views`](https://github.com/mrleepee/miroclaw/tree/main/frontend/src/views) (Workflow views), [`backend/app/agents/round_orchestrator.py`](https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/round_orchestrator.py) (Round orchestrator), [`backend/app/services/local_graph/graph_service.py`](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/local_graph/graph_service.py) (Graph service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User workflow"]
  node_workflow["Workflow views"]
  node_build_ui["Graph build"]
  node_setup_ui["Environment setup<br/>[Step2EnvSetup.vue]"]
  node_run_ui["Simulation controls"]
  node_report_ui["Report view<br/>[Step4Report.vue]"]
  node_interaction_ui["Deep interaction"]
  node_frontend_api["API clients"]
end

subgraph group_api["Backend API"]
  node_graph_api["Graph endpoints<br/>[graph.py]"]
  node_simulation_api["Simulation endpoints<br/>[simulation.py]"]
  node_report_api["Report endpoints<br/>[report.py]"]
  node_analytics_api["Analytics endpoints<br/>[analytics.py]"]
  node_report_store[("Project records<br/>[project.py]")]
end

subgraph group_knowledge["Knowledge graph"]
  node_graph_builder["Graph builder<br/>[graph_builder.py]"]
  node_ontology["Ontology generation"]
  node_entity_reader["Entity filtering"]
  node_graph_search["Graph search"]
  node_local_graph["Graph service<br/>[graph_service.py]"]
  node_neo4j[("Neo4j<br/>[neo4j_client.py]")]
end

subgraph group_simulation["Simulation"]
  node_manager["Simulation manager"]
  node_rounds["Round orchestrator"]
  node_agents["Simulation agents"]
  node_research_tools["Research tools<br/>[research.py]"]
  node_browser["Browser research<br/>[camofox_client.py]"]
  node_oasis["OASIS platforms<br/>[oasis_platform.py]"]
  node_curator["Graph curation<br/>[curator_agent.py]"]
end

subgraph group_analysis["Forecasting and analysis"]
  node_oracle["Oracle forecasting<br/>[oracle_agent.py]"]
  node_report_agent["Report generation<br/>[report_agent.py]"]
  node_query_tools["Simulation analysis"]
end

node_user(("Researcher"))
node_web_browser_service{{"Camofox browser"}}
node_social_service{{"OASIS"}}
node_llm{{"LLM API"}}

node_user -->|"uses"| node_workflow
node_workflow -->|"starts build"| node_build_ui
node_workflow -->|"configures"| node_setup_ui
node_workflow -->|"runs"| node_run_ui
node_workflow -->|"reviews"| node_report_ui
node_workflow -->|"continues to chat"| node_interaction_ui
node_build_ui -->|"submits graph work"| node_frontend_api
node_setup_ui -->|"submits setup"| node_frontend_api
node_run_ui -->|"controls simulation"| node_frontend_api
node_report_ui -->|"requests report"| node_frontend_api
node_interaction_ui -->|"sends messages"| node_frontend_api
node_frontend_api -->|"calls"| node_graph_api
node_frontend_api -->|"calls"| node_simulation_api
node_frontend_api -->|"calls"| node_report_api
node_frontend_api -->|"calls"| node_analytics_api
node_graph_api -->|"builds graph"| node_graph_builder
node_graph_builder -->|"generates ontology"| node_ontology
node_graph_builder -->|"writes graph"| node_local_graph
node_simulation_api -->|"prepares and runs"| node_manager
node_manager -->|"filters graph entities"| node_entity_reader
node_entity_reader -->|"reads entities"| node_local_graph
node_manager -->|"runs rounds"| node_rounds
node_rounds -->|"dispatches phases"| node_agents
node_rounds -->|"executes research actions"| node_research_tools
node_research_tools -->|"searches and extracts"| node_browser
node_browser -.->|"requests pages"| node_web_browser_service
node_rounds -->|"coordinates simulation"| node_oasis
node_oasis -.->|"uses platforms"| node_social_service
node_rounds -->|"curates findings"| node_curator
node_curator -->|"updates triples"| node_local_graph
node_rounds -->|"requests forecasts"| node_oracle
node_oracle -->|"reads graph context"| node_local_graph
node_report_api -->|"generates report"| node_report_agent
node_report_agent -->|"uses forecasts"| node_oracle
node_report_agent -->|"analyzes behavior"| node_query_tools
node_query_tools -->|"reads simulation data"| node_manager
node_report_api -->|"reads and writes reports"| node_report_store
node_local_graph -->|"queries and updates"| node_neo4j
node_graph_search -->|"searches graph"| node_local_graph
node_agents -.->|"requests responses"| node_llm
node_report_agent -.->|"requests analysis"| node_llm

click node_workflow "https://github.com/mrleepee/miroclaw/tree/main/frontend/src/views"
click node_build_ui "https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step1GraphBuild.vue"
click node_setup_ui "https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step2EnvSetup.vue"
click node_run_ui "https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step3Simulation.vue"
click node_report_ui "https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step4Report.vue"
click node_interaction_ui "https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step5Interaction.vue"
click node_frontend_api "https://github.com/mrleepee/miroclaw/tree/main/frontend/src/api"
click node_graph_api "https://github.com/mrleepee/miroclaw/blob/main/backend/app/api/graph.py"
click node_simulation_api "https://github.com/mrleepee/miroclaw/blob/main/backend/app/api/simulation.py"
click node_report_api "https://github.com/mrleepee/miroclaw/blob/main/backend/app/api/report.py"
click node_analytics_api "https://github.com/mrleepee/miroclaw/blob/main/backend/app/api/analytics.py"
click node_graph_builder "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/graph_builder.py"
click node_ontology "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/ontology_generator.py"
click node_entity_reader "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/graph_entity_reader.py"
click node_graph_search "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/graph_search_tools.py"
click node_local_graph "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/local_graph/graph_service.py"
click node_neo4j "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/local_graph/neo4j_client.py"
click node_manager "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/simulation_manager.py"
click node_rounds "https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/round_orchestrator.py"
click node_agents "https://github.com/mrleepee/miroclaw/tree/main/backend/app/agents"
click node_research_tools "https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/tools/research.py"
click node_browser "https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/tools/camofox_client.py"
click node_oasis "https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/tools/oasis_platform.py"
click node_curator "https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/curator_agent.py"
click node_oracle "https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/oracle_agent.py"
click node_report_agent "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/report_agent.py"
click node_query_tools "https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/simulation_query_tools.py"
click node_report_store "https://github.com/mrleepee/miroclaw/blob/main/backend/app/models/project.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_workflow,node_build_ui,node_setup_ui,node_run_ui,node_report_ui,node_interaction_ui,node_frontend_api,node_web_browser_service toneBlue
class node_graph_api,node_simulation_api,node_report_api,node_analytics_api,node_report_store toneAmber
class node_graph_builder,node_ontology,node_entity_reader,node_graph_search,node_local_graph,node_neo4j,node_llm toneMint
class node_manager,node_rounds,node_agents,node_research_tools,node_browser,node_oasis,node_curator toneRose
class node_oracle,node_report_agent,node_query_tools,node_user,node_social_service toneIndigo
```

## Components

### User workflow

- [Workflow views](https://github.com/mrleepee/miroclaw/tree/main/frontend/src/views): `frontend/src/views`
- [Graph build](https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step1GraphBuild.vue): `frontend/src/components/Step1GraphBuild.vue`
- [Environment setup](https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step2EnvSetup.vue): `frontend/src/components/Step2EnvSetup.vue`
- [Simulation controls](https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step3Simulation.vue): `frontend/src/components/Step3Simulation.vue`
- [Report view](https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step4Report.vue): `frontend/src/components/Step4Report.vue`
- [Deep interaction](https://github.com/mrleepee/miroclaw/blob/main/frontend/src/components/Step5Interaction.vue): `frontend/src/components/Step5Interaction.vue`
- [API clients](https://github.com/mrleepee/miroclaw/tree/main/frontend/src/api): `frontend/src/api`

### Backend API

- [Graph endpoints](https://github.com/mrleepee/miroclaw/blob/main/backend/app/api/graph.py): `backend/app/api/graph.py`
- [Simulation endpoints](https://github.com/mrleepee/miroclaw/blob/main/backend/app/api/simulation.py): `backend/app/api/simulation.py`
- [Report endpoints](https://github.com/mrleepee/miroclaw/blob/main/backend/app/api/report.py): `backend/app/api/report.py`
- [Analytics endpoints](https://github.com/mrleepee/miroclaw/blob/main/backend/app/api/analytics.py): `backend/app/api/analytics.py`
- [Project records](https://github.com/mrleepee/miroclaw/blob/main/backend/app/models/project.py): `backend/app/models/project.py`

### Knowledge graph

- [Graph builder](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/graph_builder.py): `backend/app/services/graph_builder.py`
- [Ontology generation](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/ontology_generator.py): `backend/app/services/ontology_generator.py`
- [Entity filtering](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/graph_entity_reader.py): `backend/app/services/graph_entity_reader.py`
- [Graph search](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/graph_search_tools.py): `backend/app/services/graph_search_tools.py`
- [Graph service](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/local_graph/graph_service.py): `backend/app/services/local_graph/graph_service.py`
- [Neo4j](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/local_graph/neo4j_client.py): `backend/app/services/local_graph/neo4j_client.py`

### Simulation

- [Simulation manager](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/simulation_manager.py): `backend/app/services/simulation_manager.py`
- [Round orchestrator](https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/round_orchestrator.py): `backend/app/agents/round_orchestrator.py`
- [Simulation agents](https://github.com/mrleepee/miroclaw/tree/main/backend/app/agents): `backend/app/agents`
- [Research tools](https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/tools/research.py): `backend/app/agents/tools/research.py`
- [Browser research](https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/tools/camofox_client.py): `backend/app/agents/tools/camofox_client.py`
- [OASIS platforms](https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/tools/oasis_platform.py): `backend/app/agents/tools/oasis_platform.py`
- [Graph curation](https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/curator_agent.py): `backend/app/agents/curator_agent.py`

### Forecasting and analysis

- [Oracle forecasting](https://github.com/mrleepee/miroclaw/blob/main/backend/app/agents/oracle_agent.py): `backend/app/agents/oracle_agent.py`
- [Report generation](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/report_agent.py): `backend/app/services/report_agent.py`
- [Simulation analysis](https://github.com/mrleepee/miroclaw/blob/main/backend/app/services/simulation_query_tools.py): `backend/app/services/simulation_query_tools.py`

### Other components

- **Researcher**
- **Camofox browser**
- **OASIS**
- **LLM API**

## Connections

- Researcher → Workflow views: uses
- Workflow views → Graph build: starts build
- Workflow views → Environment setup: configures
- Workflow views → Simulation controls: runs
- Workflow views → Report view: reviews
- Workflow views → Deep interaction: continues to chat
- Graph build → API clients: submits graph work
- Environment setup → API clients: submits setup
- Simulation controls → API clients: controls simulation
- Report view → API clients: requests report
- Deep interaction → API clients: sends messages
- API clients → Graph endpoints: calls
- API clients → Simulation endpoints: calls
- API clients → Report endpoints: calls
- API clients → Analytics endpoints: calls
- Graph endpoints → Graph builder: builds graph
- Graph builder → Ontology generation: generates ontology
- Graph builder → Graph service: writes graph
- Simulation endpoints → Simulation manager: prepares and runs
- Simulation manager → Entity filtering: filters graph entities
- Entity filtering → Graph service: reads entities
- Simulation manager → Round orchestrator: runs rounds
- Round orchestrator → Simulation agents: dispatches phases
- Round orchestrator → Research tools: executes research actions
- Research tools → Browser research: searches and extracts
- Browser research → Camofox browser: requests pages
- Round orchestrator → OASIS platforms: coordinates simulation
- OASIS platforms → OASIS: uses platforms
- Round orchestrator → Graph curation: curates findings
- Graph curation → Graph service: updates triples
- Round orchestrator → Oracle forecasting: requests forecasts
- Oracle forecasting → Graph service: reads graph context
- Report endpoints → Report generation: generates report
- Report generation → Oracle forecasting: uses forecasts
- Report generation → Simulation analysis: analyzes behavior
- Simulation analysis → Simulation manager: reads simulation data
- Report endpoints → Project records: reads and writes reports
- Graph service → Neo4j: queries and updates
- Graph search → Graph service: searches graph
- Simulation agents → LLM API: requests responses
- Report generation → LLM API: requests analysis