# aluro7in/mirofish architecture

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

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

## Overview

MiroFish is a multi-agent prediction engine: users submit seed documents and a natural-language prediction requirement, build a knowledge graph, configure and run a simulated social environment, then inspect reports and interact with the simulated world. The README documents graph construction, entity/persona and environment setup, parallel Twitter/Reddit simulation, report analysis, and interaction. The graph reflects that workflow; unsampled API and service implementations are represented only where their responsibilities are explicit in the README or file tree.

Main entry points: [`backend/app/api/graph.py`](https://github.com/aluro7in/mirofish/blob/main/backend/app/api/graph.py) (Graph routes), [`backend/app/api/simulation.py`](https://github.com/aluro7in/mirofish/blob/main/backend/app/api/simulation.py) (Simulation routes), [`backend/app/services/simulation_manager.py`](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/simulation_manager.py) (Simulation preparation), [`frontend/src/views/Process.vue`](https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/Process.vue) (Graph workflow)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["User experience"]
  node_home["Home and history<br/>[Home.vue]"]
  node_process["Graph workflow<br/>[Process.vue]"]
  node_simulation_ui["Simulation workflow<br/>[SimulationView.vue]"]
  node_report_ui["Report view<br/>[ReportView.vue]"]
  node_interaction_ui["World interaction"]
  node_graph_api_client["Graph API client<br/>[graph.js]"]
  node_simulation_api_client["Simulation API client<br/>[simulation.js]"]
  node_report_api_client["Report API client<br/>[report.js]"]
end

subgraph group_knowledge["Seed and graph"]
  node_graph_api["Graph routes<br/>[graph.py]"]
  node_project_state[("Project state<br/>[project.py]")]
  node_file_parser["Seed text extraction<br/>[file_parser.py]"]
  node_ontology["Ontology generation"]
  node_graph_builder["Graph construction<br/>[graph_builder.py]"]
end

subgraph group_simulation["Simulation"]
  node_simulation_api["Simulation routes<br/>[simulation.py]"]
  node_simulation_manager["Simulation preparation"]
  node_entity_reader["Entity reading"]
  node_profile_generator["Agent profiles"]
  node_config_generator["Simulation configuration"]
  node_simulation_runner["Simulation runner"]
end

subgraph group_insights["Reports and interaction"]
  node_report_api["Report routes<br/>[report.py]"]
  node_report_agent["Report analysis agent<br/>[report_agent.py]"]
  node_interaction_tools["Simulation interaction tools<br/>[zep_tools.py]"]
end

node_user(("User"))
node_zep_graph[("Zep graph memory")]
node_oasis["OASIS engine"]
node_llm["LLM service"]

node_user -->|"starts"| node_home
node_home -->|"opens workflow"| node_process
node_user -->|"submits seeds"| node_process
node_process -->|"requests graph work"| node_graph_api_client
node_graph_api_client -->|"calls"| node_graph_api
node_graph_api -->|"stores project"| node_project_state
node_graph_api -->|"extracts seed text"| node_file_parser
node_graph_api -->|"generates ontology"| node_ontology
node_ontology -->|"generates with"| node_llm
node_graph_api -->|"builds graph"| node_graph_builder
node_graph_builder -->|"writes graph"| node_zep_graph
node_user -->|"sets simulation"| node_simulation_ui
node_simulation_ui -->|"requests simulation"| node_simulation_api_client
node_simulation_api_client -->|"calls"| node_simulation_api
node_simulation_api -->|"prepares simulation"| node_simulation_manager
node_simulation_manager -->|"reads entities"| node_entity_reader
node_entity_reader -->|"reads graph"| node_zep_graph
node_simulation_manager -->|"generates profiles"| node_profile_generator
node_profile_generator -->|"generates with"| node_llm
node_simulation_manager -->|"generates configuration"| node_config_generator
node_config_generator -->|"generates with"| node_llm
node_simulation_api -->|"starts and monitors"| node_simulation_runner
node_simulation_runner -->|"runs simulation"| node_oasis
node_user -->|"requests report"| node_report_ui
node_report_ui -->|"requests analysis"| node_report_api_client
node_report_api_client -->|"calls"| node_report_api
node_report_api -->|"creates report"| node_report_agent
node_report_agent -->|"analyzes with"| node_llm
node_user -->|"interacts"| node_interaction_ui
node_interaction_ui -->|"sends interaction"| node_simulation_api_client
node_simulation_api -->|"dispatches interaction"| node_interaction_tools
node_interaction_tools -->|"accesses graph memory"| node_zep_graph

click node_home "https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/Home.vue"
click node_process "https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/Process.vue"
click node_simulation_ui "https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/SimulationView.vue"
click node_report_ui "https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/ReportView.vue"
click node_interaction_ui "https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/InteractionView.vue"
click node_graph_api_client "https://github.com/aluro7in/mirofish/blob/main/frontend/src/api/graph.js"
click node_simulation_api_client "https://github.com/aluro7in/mirofish/blob/main/frontend/src/api/simulation.js"
click node_report_api_client "https://github.com/aluro7in/mirofish/blob/main/frontend/src/api/report.js"
click node_graph_api "https://github.com/aluro7in/mirofish/blob/main/backend/app/api/graph.py"
click node_project_state "https://github.com/aluro7in/mirofish/blob/main/backend/app/models/project.py"
click node_file_parser "https://github.com/aluro7in/mirofish/blob/main/backend/app/utils/file_parser.py"
click node_ontology "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/ontology_generator.py"
click node_graph_builder "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/graph_builder.py"
click node_simulation_api "https://github.com/aluro7in/mirofish/blob/main/backend/app/api/simulation.py"
click node_simulation_manager "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/simulation_manager.py"
click node_entity_reader "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/zep_entity_reader.py"
click node_profile_generator "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/oasis_profile_generator.py"
click node_config_generator "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/simulation_config_generator.py"
click node_simulation_runner "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/simulation_runner.py"
click node_report_api "https://github.com/aluro7in/mirofish/blob/main/backend/app/api/report.py"
click node_report_agent "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/report_agent.py"
click node_interaction_tools "https://github.com/aluro7in/mirofish/blob/main/backend/app/services/zep_tools.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_process,node_simulation_ui,node_report_ui,node_interaction_ui,node_graph_api_client,node_simulation_api_client,node_report_api_client,node_user toneBlue
class node_graph_api,node_project_state,node_file_parser,node_ontology,node_graph_builder,node_zep_graph toneAmber
class node_simulation_api,node_simulation_manager,node_entity_reader,node_profile_generator,node_config_generator,node_simulation_runner toneMint
class node_report_api,node_report_agent,node_interaction_tools toneRose
class node_oasis,node_llm toneIndigo
```

## Components

### User experience

- [Home and history](https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/Home.vue): `frontend/src/views/Home.vue`
- [Graph workflow](https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/Process.vue): `frontend/src/views/Process.vue`
- [Simulation workflow](https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/SimulationView.vue): `frontend/src/views/SimulationView.vue`
- [Report view](https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/ReportView.vue): `frontend/src/views/ReportView.vue`
- [World interaction](https://github.com/aluro7in/mirofish/blob/main/frontend/src/views/InteractionView.vue): `frontend/src/views/InteractionView.vue`
- [Graph API client](https://github.com/aluro7in/mirofish/blob/main/frontend/src/api/graph.js): `frontend/src/api/graph.js`
- [Simulation API client](https://github.com/aluro7in/mirofish/blob/main/frontend/src/api/simulation.js): `frontend/src/api/simulation.js`
- [Report API client](https://github.com/aluro7in/mirofish/blob/main/frontend/src/api/report.js): `frontend/src/api/report.js`

### Seed and graph

- [Graph routes](https://github.com/aluro7in/mirofish/blob/main/backend/app/api/graph.py): `backend/app/api/graph.py`
- [Project state](https://github.com/aluro7in/mirofish/blob/main/backend/app/models/project.py): `backend/app/models/project.py`
- [Seed text extraction](https://github.com/aluro7in/mirofish/blob/main/backend/app/utils/file_parser.py): `backend/app/utils/file_parser.py`
- [Ontology generation](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/ontology_generator.py): `backend/app/services/ontology_generator.py`
- [Graph construction](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/graph_builder.py): `backend/app/services/graph_builder.py`

### Simulation

- [Simulation routes](https://github.com/aluro7in/mirofish/blob/main/backend/app/api/simulation.py): `backend/app/api/simulation.py`
- [Simulation preparation](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/simulation_manager.py): `backend/app/services/simulation_manager.py`
- [Entity reading](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/zep_entity_reader.py): `backend/app/services/zep_entity_reader.py`
- [Agent profiles](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/oasis_profile_generator.py): `backend/app/services/oasis_profile_generator.py`
- [Simulation configuration](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/simulation_config_generator.py): `backend/app/services/simulation_config_generator.py`
- [Simulation runner](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/simulation_runner.py): `backend/app/services/simulation_runner.py`

### Reports and interaction

- [Report routes](https://github.com/aluro7in/mirofish/blob/main/backend/app/api/report.py): `backend/app/api/report.py`
- [Report analysis agent](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/report_agent.py): `backend/app/services/report_agent.py`
- [Simulation interaction tools](https://github.com/aluro7in/mirofish/blob/main/backend/app/services/zep_tools.py): `backend/app/services/zep_tools.py`

### Other components

- **User**
- **Zep graph memory**
- **OASIS engine**
- **LLM service**

## Connections

- User → Home and history: starts
- Home and history → Graph workflow: opens workflow
- User → Graph workflow: submits seeds
- Graph workflow → Graph API client: requests graph work
- Graph API client → Graph routes: calls
- Graph routes → Project state: stores project
- Graph routes → Seed text extraction: extracts seed text
- Graph routes → Ontology generation: generates ontology
- Ontology generation → LLM service: generates with
- Graph routes → Graph construction: builds graph
- Graph construction → Zep graph memory: writes graph
- User → Simulation workflow: sets simulation
- Simulation workflow → Simulation API client: requests simulation
- Simulation API client → Simulation routes: calls
- Simulation routes → Simulation preparation: prepares simulation
- Simulation preparation → Entity reading: reads entities
- Entity reading → Zep graph memory: reads graph
- Simulation preparation → Agent profiles: generates profiles
- Agent profiles → LLM service: generates with
- Simulation preparation → Simulation configuration: generates configuration
- Simulation configuration → LLM service: generates with
- Simulation routes → Simulation runner: starts and monitors
- Simulation runner → OASIS engine: runs simulation
- User → Report view: requests report
- Report view → Report API client: requests analysis
- Report API client → Report routes: calls
- Report routes → Report analysis agent: creates report
- Report analysis agent → LLM service: analyzes with
- User → World interaction: interacts
- World interaction → Simulation API client: sends interaction
- Simulation routes → Simulation interaction tools: dispatches interaction
- Simulation interaction tools → Zep graph memory: accesses graph memory