# 666ghj/mirofish architecture

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

- Interactive diagram: https://gitdiagram.com/666ghj/mirofish
- Repository: https://github.com/666ghj/mirofish

## Overview

MiroFish is a web-based multi-agent prediction engine. Users upload seed material and describe a prediction; the product builds a knowledge graph, prepares agent personas and simulation settings, runs social simulations, generates a report, and supports follow-up interaction with agents and the report agent. The graph preserves those documented stages and the major report, history, and Zep-backed capabilities. Some implementation files were not sampled, so their internal calls are not inferred; edges use documented workflow statements or visible references.

Main entry points: [`backend/app/api/simulation.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/api/simulation.py) (Simulation API), [`frontend/src/views/Process.vue`](https://github.com/666ghj/mirofish/blob/main/frontend/src/views/Process.vue) (Workflow views), [`backend/app/api/graph.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/api/graph.py) (Graph API), [`backend/app/services/graph_builder.py`](https://github.com/666ghj/mirofish/blob/main/backend/app/services/graph_builder.py) (Graph builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_webflow["Workflow views<br/>[Process.vue]"]
  node_history["Project history"]
end

subgraph group_project["Project and graph"]
  node_graphapi["Graph API<br/>[graph.py]"]
  node_graphbuild["Graph builder<br/>[graph_builder.py]"]
  node_projectstate[("Project state<br/>[project.py]")]
  node_fileparse["Seed parsing<br/>[file_parser.py]"]
end

subgraph group_simulation["Simulation engine"]
  node_simulationapi["Simulation API<br/>[simulation.py]"]
  node_entityreader["Entity reader"]
  node_persona["Persona generator"]
  node_simconfig["Simulation config"]
  node_simmanager[("Simulation manager")]
  node_simrunner["Simulation runner"]
end

subgraph group_analysis["Reports and memory"]
  node_reportapi["Report API<br/>[report.py]"]
  node_reportagent["Report agent<br/>[report_agent.py]"]
  node_zepmemory["Graph memory updates"]
  node_zeptools["Zep query tools<br/>[zep_tools.py]"]
  node_llm["LLM client<br/>[llm_client.py]"]
end

node_user(("User"))
node_zep[("Zep Cloud")]
node_oasis["OASIS engine"]

node_user -->|"submits materials"| node_webflow
node_webflow -->|"requests graph build"| node_graphapi
node_graphapi -.->|"builds graph"| node_graphbuild
node_graphapi -.->|"updates project"| node_projectstate
node_graphbuild -.->|"parses seed"| node_fileparse
node_graphbuild -->|"constructs GraphRAG"| node_zep
node_webflow -->|"starts simulation setup"| node_simulationapi
node_simulationapi -->|"filters entities"| node_entityreader
node_simulationapi -.->|"manages runs"| node_simmanager
node_simmanager -.->|"generates profiles"| node_persona
node_simmanager -.->|"generates settings"| node_simconfig
node_simulationapi -.->|"runs simulation"| node_simrunner
node_simrunner -->|"executes agents"| node_oasis
node_simrunner -->|"updates graph memory"| node_zepmemory
node_user -->|"requests report"| node_reportapi
node_reportapi -->|"generates report"| node_reportagent
node_reportagent -->|"calls model"| node_llm
node_reportagent -->|"uses query tools"| node_zeptools
node_zeptools -->|"queries graph"| node_zep
node_user -->|"interacts with agents"| node_zepmemory
node_history -->|"loads history"| node_simulationapi

click node_webflow "https://github.com/666ghj/mirofish/blob/main/frontend/src/views/Process.vue"
click node_history "https://github.com/666ghj/mirofish/blob/main/frontend/src/components/HistoryDatabase.vue"
click node_graphapi "https://github.com/666ghj/mirofish/blob/main/backend/app/api/graph.py"
click node_graphbuild "https://github.com/666ghj/mirofish/blob/main/backend/app/services/graph_builder.py"
click node_projectstate "https://github.com/666ghj/mirofish/blob/main/backend/app/models/project.py"
click node_fileparse "https://github.com/666ghj/mirofish/blob/main/backend/app/utils/file_parser.py"
click node_simulationapi "https://github.com/666ghj/mirofish/blob/main/backend/app/api/simulation.py"
click node_entityreader "https://github.com/666ghj/mirofish/blob/main/backend/app/services/zep_entity_reader.py"
click node_persona "https://github.com/666ghj/mirofish/blob/main/backend/app/services/oasis_profile_generator.py"
click node_simconfig "https://github.com/666ghj/mirofish/blob/main/backend/app/services/simulation_config_generator.py"
click node_simmanager "https://github.com/666ghj/mirofish/blob/main/backend/app/services/simulation_manager.py"
click node_simrunner "https://github.com/666ghj/mirofish/blob/main/backend/app/services/simulation_runner.py"
click node_reportapi "https://github.com/666ghj/mirofish/blob/main/backend/app/api/report.py"
click node_reportagent "https://github.com/666ghj/mirofish/blob/main/backend/app/services/report_agent.py"
click node_zepmemory "https://github.com/666ghj/mirofish/blob/main/backend/app/services/zep_graph_memory_updater.py"
click node_zeptools "https://github.com/666ghj/mirofish/blob/main/backend/app/services/zep_tools.py"
click node_llm "https://github.com/666ghj/mirofish/blob/main/backend/app/utils/llm_client.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_webflow,node_history,node_user toneBlue
class node_graphapi,node_graphbuild,node_projectstate,node_fileparse,node_zep toneAmber
class node_simulationapi,node_entityreader,node_persona,node_simconfig,node_simmanager,node_simrunner toneMint
class node_reportapi,node_reportagent,node_zepmemory,node_zeptools,node_llm toneRose
class node_oasis toneIndigo
```

## Components

### Web experience

- [Workflow views](https://github.com/666ghj/mirofish/blob/main/frontend/src/views/Process.vue): `frontend/src/views/Process.vue`
- [Project history](https://github.com/666ghj/mirofish/blob/main/frontend/src/components/HistoryDatabase.vue): `frontend/src/components/HistoryDatabase.vue`

### Project and graph

- [Graph API](https://github.com/666ghj/mirofish/blob/main/backend/app/api/graph.py): `backend/app/api/graph.py`
- [Graph builder](https://github.com/666ghj/mirofish/blob/main/backend/app/services/graph_builder.py): `backend/app/services/graph_builder.py`
- [Project state](https://github.com/666ghj/mirofish/blob/main/backend/app/models/project.py): `backend/app/models/project.py`
- [Seed parsing](https://github.com/666ghj/mirofish/blob/main/backend/app/utils/file_parser.py): `backend/app/utils/file_parser.py`

### Simulation engine

- [Simulation API](https://github.com/666ghj/mirofish/blob/main/backend/app/api/simulation.py): `backend/app/api/simulation.py`
- [Entity reader](https://github.com/666ghj/mirofish/blob/main/backend/app/services/zep_entity_reader.py): `backend/app/services/zep_entity_reader.py`
- [Persona generator](https://github.com/666ghj/mirofish/blob/main/backend/app/services/oasis_profile_generator.py): `backend/app/services/oasis_profile_generator.py`
- [Simulation config](https://github.com/666ghj/mirofish/blob/main/backend/app/services/simulation_config_generator.py): `backend/app/services/simulation_config_generator.py`
- [Simulation manager](https://github.com/666ghj/mirofish/blob/main/backend/app/services/simulation_manager.py): `backend/app/services/simulation_manager.py`
- [Simulation runner](https://github.com/666ghj/mirofish/blob/main/backend/app/services/simulation_runner.py): `backend/app/services/simulation_runner.py`

### Reports and memory

- [Report API](https://github.com/666ghj/mirofish/blob/main/backend/app/api/report.py): `backend/app/api/report.py`
- [Report agent](https://github.com/666ghj/mirofish/blob/main/backend/app/services/report_agent.py): `backend/app/services/report_agent.py`
- [Graph memory updates](https://github.com/666ghj/mirofish/blob/main/backend/app/services/zep_graph_memory_updater.py): `backend/app/services/zep_graph_memory_updater.py`
- [Zep query tools](https://github.com/666ghj/mirofish/blob/main/backend/app/services/zep_tools.py): `backend/app/services/zep_tools.py`
- [LLM client](https://github.com/666ghj/mirofish/blob/main/backend/app/utils/llm_client.py): `backend/app/utils/llm_client.py`

### Other components

- **User**
- **Zep Cloud**
- **OASIS engine**

## Connections

- User → Workflow views: submits materials (evidence: `README.md`)
- Workflow views → Graph API: requests graph build (evidence: `frontend/src/views/Process.vue`)
- Graph API → Graph builder: builds graph
- Graph API → Project state: updates project
- Graph builder → Seed parsing: parses seed
- Graph builder → Zep Cloud: constructs GraphRAG (evidence: `README.md`)
- Workflow views → Simulation API: starts simulation setup (evidence: `README.md`)
- Simulation API → Entity reader: filters entities (evidence: `backend/app/api/simulation.py`)
- Simulation API → Simulation manager: manages runs (evidence: `backend/app/api/simulation.py`)
- Simulation manager → Persona generator: generates profiles (evidence: `backend/app/services/simulation_manager.py`)
- Simulation manager → Simulation config: generates settings (evidence: `backend/app/services/simulation_manager.py`)
- Simulation API → Simulation runner: runs simulation (evidence: `backend/app/api/simulation.py`)
- Simulation runner → OASIS engine: executes agents (evidence: `README.md`)
- Simulation runner → Graph memory updates: updates graph memory (evidence: `backend/app/services/simulation_runner.py`)
- User → Report API: requests report (evidence: `README.md`)
- Report API → Report agent: generates report (evidence: `backend/app/api/report.py`)
- Report agent → LLM client: calls model (evidence: `backend/app/services/report_agent.py`)
- Report agent → Zep query tools: uses query tools (evidence: `backend/app/services/report_agent.py`)
- Zep query tools → Zep Cloud: queries graph (evidence: `backend/app/services/zep_tools.py`)
- User → Graph memory updates: interacts with agents (evidence: `README.md`)
- Project history → Simulation API: loads history (evidence: `frontend/src/components/HistoryDatabase.vue`)
