# bocai-harry/mirofish architecture

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

- Interactive diagram: https://gitdiagram.com/bocai-harry/mirofish
- Repository: https://github.com/bocai-harry/mirofish

## Overview

MiroFish is a multi-agent prediction engine: users submit seed material and a natural-language prediction requirement, build a graph-backed world, configure and run social simulations, then generate a report and interact with simulated agents or the report agent. The diagram preserves the README’s five domain stages and key graph, memory, OASIS, reporting, and interaction capabilities. Source excerpts establish several backend calls and frontend API relationships; unsampled subsystems are included where documented, with uncertain links left dashed.

Main entry points: [`backend/app/api/graph.py`](https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/graph.py) (Graph endpoints), [`backend/app/services/simulation_manager.py`](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_manager.py) (Simulation lifecycle), [`backend/app/api/simulation.py`](https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/simulation.py) (Simulation endpoints), [`backend/app/services/simulation_runner.py`](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_runner.py) (OASIS runner)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User experience"]
  node_home["Project entry<br/>[Home.vue]"]
  node_pending["Pending upload<br/>[pendingUpload.js]"]
  node_process["Workflow process<br/>[Process.vue]"]
  node_graph_ui["Graph building"]
  node_env_ui["Environment setup<br/>[Step2EnvSetup.vue]"]
  node_run_ui["Simulation controls"]
  node_report_ui["Report view<br/>[Step4Report.vue]"]
  node_interaction_ui["World interaction"]
  node_graph_api_client["Graph API client<br/>[graph.js]"]
  node_sim_api_client["Simulation API client<br/>[simulation.js]"]
  node_report_api_client["Report API client<br/>[report.js]"]
end

subgraph group_graph["Seed and graph"]
  node_graph_routes["Graph endpoints<br/>[graph.py]"]
  node_text_parse["Seed text parsing<br/>[file_parser.py]"]
  node_text_process["Text processing<br/>[text_processor.py]"]
  node_ontology["Ontology generation"]
  node_graph_builder["Graph construction<br/>[graph_builder.py]"]
  node_zep[("Zep graph memory")]
end

subgraph group_simulation["World simulation"]
  node_simulation_routes["Simulation endpoints<br/>[simulation.py]"]
  node_entity_reader["Entity selection"]
  node_profile_gen["Agent profiles"]
  node_config_gen["Simulation configuration"]
  node_sim_manager["Simulation lifecycle"]
  node_sim_runner["OASIS runner"]
  node_sim_ipc["Simulation IPC<br/>[simulation_ipc.py]"]
  node_memory_updater["Temporal memory updates"]
  node_oasis["OASIS engine"]
  node_simulation_data[("Simulation data<br/>[config.py]")]
end

subgraph group_reporting["Reports and interaction"]
  node_report_routes["Report endpoints<br/>[report.py]"]
  node_report_agent["Report agent<br/>[report_agent.py]"]
  node_zep_tools["Graph retrieval tools<br/>[zep_tools.py]"]
  node_report_store[("Report history<br/>[report.py]")]
end

subgraph group_platform["Runtime foundations"]
  node_project_store[("Project state<br/>[project.py]")]
  node_task_state["Task tracking<br/>[task.py]"]
end

node_user(("User"))

node_user -->|"submits seed"| node_home
node_home -->|"stages upload"| node_pending
node_pending -->|"provides upload"| node_process
node_process -->|"renders"| node_graph_ui
node_process -->|"requests graph"| node_graph_api_client
node_graph_ui -->|"calls"| node_sim_api_client
node_graph_ui -->|"calls"| node_graph_api_client
node_process -->|"renders"| node_env_ui
node_env_ui -->|"requests setup"| node_sim_api_client
node_user -->|"starts run"| node_run_ui
node_run_ui -->|"controls run"| node_sim_api_client
node_user -->|"reviews report"| node_report_ui
node_report_ui -->|"requests report"| node_report_api_client
node_user -->|"interacts"| node_interaction_ui
node_interaction_ui -.->|"uses report chat"| node_report_api_client
node_graph_api_client -.->|"HTTP requests"| node_graph_routes
node_sim_api_client -.->|"HTTP requests"| node_simulation_routes
node_report_api_client -.->|"HTTP requests"| node_report_routes
node_graph_routes -->|"parses uploads"| node_text_parse
node_graph_routes -->|"processes text"| node_text_process
node_graph_routes -->|"generates ontology"| node_ontology
node_graph_routes -->|"builds graph"| node_graph_builder
node_graph_routes -->|"tracks tasks"| node_task_state
node_graph_routes -->|"persists project"| node_project_store
node_graph_builder -.->|"writes graph"| node_zep
node_simulation_routes -->|"manages runs"| node_sim_manager
node_simulation_routes -->|"filters entities"| node_entity_reader
node_simulation_routes -->|"reads run status"| node_sim_runner
node_simulation_routes -->|"reads project"| node_project_store
node_sim_manager -->|"reads entities"| node_entity_reader
node_sim_manager -->|"generates profiles"| node_profile_gen
node_sim_manager -->|"generates parameters"| node_config_gen
node_sim_manager -->|"stores state"| node_simulation_data
node_entity_reader -->|"reads graph"| node_zep
node_profile_gen -.->|"reads graph memory"| node_zep
node_sim_runner -->|"uses IPC"| node_sim_ipc
node_sim_runner -->|"updates memory"| node_memory_updater
node_sim_runner -.->|"runs simulation"| node_oasis
node_sim_runner -.->|"writes run data"| node_simulation_data
node_report_routes -->|"generates and chats"| node_report_agent
node_report_routes -->|"loads simulation"| node_sim_manager
node_report_routes -->|"searches graph"| node_zep_tools
node_report_routes -->|"lists reports"| node_report_store
node_report_agent -->|"uses retrieval tools"| node_zep_tools
node_zep_tools -.->|"queries graph"| node_zep
node_profile_gen -.->|"injects agent memory"| node_zep

click node_home "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/views/Home.vue"
click node_pending "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/store/pendingUpload.js"
click node_process "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/views/Process.vue"
click node_graph_ui "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step1GraphBuild.vue"
click node_env_ui "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step2EnvSetup.vue"
click node_run_ui "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step3Simulation.vue"
click node_report_ui "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step4Report.vue"
click node_interaction_ui "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step5Interaction.vue"
click node_graph_api_client "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/api/graph.js"
click node_sim_api_client "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/api/simulation.js"
click node_report_api_client "https://github.com/bocai-harry/mirofish/blob/main/frontend/src/api/report.js"
click node_graph_routes "https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/graph.py"
click node_text_parse "https://github.com/bocai-harry/mirofish/blob/main/backend/app/utils/file_parser.py"
click node_text_process "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/text_processor.py"
click node_ontology "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/ontology_generator.py"
click node_graph_builder "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/graph_builder.py"
click node_simulation_routes "https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/simulation.py"
click node_entity_reader "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/zep_entity_reader.py"
click node_profile_gen "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/oasis_profile_generator.py"
click node_config_gen "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_config_generator.py"
click node_sim_manager "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_manager.py"
click node_sim_runner "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_runner.py"
click node_sim_ipc "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_ipc.py"
click node_memory_updater "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/zep_graph_memory_updater.py"
click node_simulation_data "https://github.com/bocai-harry/mirofish/blob/main/backend/app/config.py"
click node_report_routes "https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/report.py"
click node_report_agent "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/report_agent.py"
click node_zep_tools "https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/zep_tools.py"
click node_report_store "https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/report.py"
click node_project_store "https://github.com/bocai-harry/mirofish/blob/main/backend/app/models/project.py"
click node_task_state "https://github.com/bocai-harry/mirofish/blob/main/backend/app/models/task.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_home,node_pending,node_process,node_graph_ui,node_env_ui,node_run_ui,node_report_ui,node_interaction_ui,node_graph_api_client,node_sim_api_client,node_report_api_client,node_user toneBlue
class node_graph_routes,node_text_parse,node_text_process,node_ontology,node_graph_builder,node_zep toneAmber
class node_simulation_routes,node_entity_reader,node_profile_gen,node_config_gen,node_sim_manager,node_sim_runner,node_sim_ipc,node_memory_updater,node_oasis,node_simulation_data toneMint
class node_report_routes,node_report_agent,node_zep_tools,node_report_store toneRose
class node_project_store,node_task_state toneIndigo
```

## Components

### User experience

- [Project entry](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/views/Home.vue): `frontend/src/views/Home.vue`
- [Pending upload](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/store/pendingUpload.js): `frontend/src/store/pendingUpload.js`
- [Workflow process](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/views/Process.vue): `frontend/src/views/Process.vue`
- [Graph building](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step1GraphBuild.vue): `frontend/src/components/Step1GraphBuild.vue`
- [Environment setup](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step2EnvSetup.vue): `frontend/src/components/Step2EnvSetup.vue`
- [Simulation controls](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step3Simulation.vue): `frontend/src/components/Step3Simulation.vue`
- [Report view](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step4Report.vue): `frontend/src/components/Step4Report.vue`
- [World interaction](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/components/Step5Interaction.vue): `frontend/src/components/Step5Interaction.vue`
- [Graph API client](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/api/graph.js): `frontend/src/api/graph.js`
- [Simulation API client](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/api/simulation.js): `frontend/src/api/simulation.js`
- [Report API client](https://github.com/bocai-harry/mirofish/blob/main/frontend/src/api/report.js): `frontend/src/api/report.js`

### Seed and graph

- [Graph endpoints](https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/graph.py): `backend/app/api/graph.py`
- [Seed text parsing](https://github.com/bocai-harry/mirofish/blob/main/backend/app/utils/file_parser.py): `backend/app/utils/file_parser.py`
- [Text processing](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/text_processor.py): `backend/app/services/text_processor.py`
- [Ontology generation](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/ontology_generator.py): `backend/app/services/ontology_generator.py`
- [Graph construction](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/graph_builder.py): `backend/app/services/graph_builder.py`
- **Zep graph memory**

### World simulation

- [Simulation endpoints](https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/simulation.py): `backend/app/api/simulation.py`
- [Entity selection](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/zep_entity_reader.py): `backend/app/services/zep_entity_reader.py`
- [Agent profiles](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/oasis_profile_generator.py): `backend/app/services/oasis_profile_generator.py`
- [Simulation configuration](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_config_generator.py): `backend/app/services/simulation_config_generator.py`
- [Simulation lifecycle](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_manager.py): `backend/app/services/simulation_manager.py`
- [OASIS runner](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_runner.py): `backend/app/services/simulation_runner.py`
- [Simulation IPC](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/simulation_ipc.py): `backend/app/services/simulation_ipc.py`
- [Temporal memory updates](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/zep_graph_memory_updater.py): `backend/app/services/zep_graph_memory_updater.py`
- **OASIS engine**
- [Simulation data](https://github.com/bocai-harry/mirofish/blob/main/backend/app/config.py): `backend/app/config.py`

### Reports and interaction

- [Report endpoints](https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/report.py): `backend/app/api/report.py`
- [Report agent](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/report_agent.py): `backend/app/services/report_agent.py`
- [Graph retrieval tools](https://github.com/bocai-harry/mirofish/blob/main/backend/app/services/zep_tools.py): `backend/app/services/zep_tools.py`
- [Report history](https://github.com/bocai-harry/mirofish/blob/main/backend/app/api/report.py): `backend/app/api/report.py`

### Runtime foundations

- [Project state](https://github.com/bocai-harry/mirofish/blob/main/backend/app/models/project.py): `backend/app/models/project.py`
- [Task tracking](https://github.com/bocai-harry/mirofish/blob/main/backend/app/models/task.py): `backend/app/models/task.py`

### Other components

- **User**

## Connections

- User → Project entry: submits seed (evidence: `frontend/src/views/Home.vue`)
- Project entry → Pending upload: stages upload (evidence: `frontend/src/views/Home.vue`)
- Pending upload → Workflow process: provides upload (evidence: `frontend/src/views/Process.vue`)
- Workflow process → Graph building: renders (evidence: `frontend/src/views/Process.vue`)
- Workflow process → Graph API client: requests graph (evidence: `frontend/src/views/Process.vue`)
- Graph building → Simulation API client: calls (evidence: `frontend/src/components/Step1GraphBuild.vue`)
- Graph building → Graph API client: calls (evidence: `frontend/src/components/Step1GraphBuild.vue`)
- Workflow process → Environment setup: renders (evidence: `frontend/src/views/Process.vue`)
- Environment setup → Simulation API client: requests setup (evidence: `frontend/src/components/Step2EnvSetup.vue`)
- User → Simulation controls: starts run (evidence: `README.md`)
- Simulation controls → Simulation API client: controls run (evidence: `frontend/src/api/simulation.js`)
- User → Report view: reviews report (evidence: `README.md`)
- Report view → Report API client: requests report (evidence: `frontend/src/components/Step4Report.vue`)
- User → World interaction: interacts (evidence: `README.md`)
- World interaction → Report API client: uses report chat
- Graph API client → Graph endpoints: HTTP requests
- Simulation API client → Simulation endpoints: HTTP requests
- Report API client → Report endpoints: HTTP requests
- Graph endpoints → Seed text parsing: parses uploads (evidence: `backend/app/api/graph.py`)
- Graph endpoints → Text processing: processes text (evidence: `backend/app/api/graph.py`)
- Graph endpoints → Ontology generation: generates ontology (evidence: `backend/app/api/graph.py`)
- Graph endpoints → Graph construction: builds graph (evidence: `backend/app/api/graph.py`)
- Graph endpoints → Task tracking: tracks tasks (evidence: `backend/app/api/graph.py`)
- Graph endpoints → Project state: persists project (evidence: `backend/app/api/graph.py`)
- Graph construction → Zep graph memory: writes graph
- Simulation endpoints → Simulation lifecycle: manages runs (evidence: `backend/app/api/simulation.py`)
- Simulation endpoints → Entity selection: filters entities (evidence: `backend/app/api/simulation.py`)
- Simulation endpoints → OASIS runner: reads run status (evidence: `backend/app/api/simulation.py`)
- Simulation endpoints → Project state: reads project (evidence: `backend/app/api/simulation.py`)
- Simulation lifecycle → Entity selection: reads entities (evidence: `backend/app/services/simulation_manager.py`)
- Simulation lifecycle → Agent profiles: generates profiles (evidence: `backend/app/services/simulation_manager.py`)
- Simulation lifecycle → Simulation configuration: generates parameters (evidence: `backend/app/services/simulation_manager.py`)
- Simulation lifecycle → Simulation data: stores state (evidence: `backend/app/services/simulation_manager.py`)
- Entity selection → Zep graph memory: reads graph (evidence: `backend/app/services/zep_entity_reader.py`)
- Agent profiles → Zep graph memory: reads graph memory
- OASIS runner → Simulation IPC: uses IPC (evidence: `backend/app/services/simulation_runner.py`)
- OASIS runner → Temporal memory updates: updates memory (evidence: `backend/app/services/simulation_runner.py`)
- OASIS runner → OASIS engine: runs simulation
- OASIS runner → Simulation data: writes run data (evidence: `backend/app/services/simulation_runner.py`)
- Report endpoints → Report agent: generates and chats (evidence: `backend/app/api/report.py`)
- Report endpoints → Simulation lifecycle: loads simulation (evidence: `backend/app/api/report.py`)
- Report endpoints → Graph retrieval tools: searches graph (evidence: `backend/app/api/report.py`)
- Report endpoints → Report history: lists reports (evidence: `backend/app/api/report.py`)
- Report agent → Graph retrieval tools: uses retrieval tools (evidence: `backend/app/services/report_agent.py`)
- Graph retrieval tools → Zep graph memory: queries graph
- Agent profiles → Zep graph memory: injects agent memory
