# igormorais123/mirofish architecture

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

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

## Overview

MiroFish INTEIA is a social multi-agent simulation product for political, institutional, and crisis scenarios. Its main workflow takes source material through knowledge extraction and graph construction, prepares agent profiles and simulation settings, runs OASIS interactions, then produces gated analytical reports and supports follow-up conversation. The README documents this end-to-end workflow and major capabilities; edges based on it cite the README. Source-index references and excerpts support the narrower implementation links. Several APIs and report internals were not sampled, so their links are limited to documented behavior.

Main entry points: [`backend/app/services/simulation_manager.py`](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/simulation_manager.py) (Simulation manager), [`frontend/src/api/index.js`](https://github.com/igormorais123/mirofish/blob/main/frontend/src/api/index.js) (Frontend API client), [`backend/app/api/graph.py`](https://github.com/igormorais123/mirofish/blob/main/backend/app/api/graph.py) (Graph API), [`backend/app/api/simulation.py`](https://github.com/igormorais123/mirofish/blob/main/backend/app/api/simulation.py) (Simulation API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_home["Project workspace<br/>[Home.vue]"]
  node_history["Simulation history"]
  node_frontendapi["Frontend API client<br/>[index.js]"]
end

subgraph group_knowledge["Knowledge preparation"]
  node_graphapi["Graph API<br/>[graph.py]"]
  node_enrichment["Web enrichment<br/>[apify_enricher.py]"]
  node_ontology["Entity extraction"]
  node_graphstore[("Graph memory<br/>[graphiti_client.py]")]
end

subgraph group_simulation["Simulation runtime"]
  node_simulationapi["Simulation API<br/>[simulation.py]"]
  node_profiles["Agent profiles"]
  node_entityreader["Entity reader"]
  node_simmanager["Simulation manager"]
  node_simrunner["OASIS runner"]
end

subgraph group_analysis["Reports and analysis"]
  node_reportapi["Report API<br/>[report.py]"]
  node_reportagent["Helena reports<br/>[report_agent.py]"]
  node_reportgate["Delivery quality gate"]
  node_helenaapi["Helena command API<br/>[helena.py]"]
end

subgraph group_platform["Shared platform"]
  node_projectstate[("Project state<br/>[project.py]")]
  node_llm["LLM client<br/>[llm_client.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
  node_logger["Structured logging<br/>[logger.py]"]
  node_safeids["Safe identifiers<br/>[safe_ids.py]"]
  node_autoresearch["Experiment engine<br/>[engine.py]"]
  node_targetbase["Research targets<br/>[base.py]"]
end

node_user(("Analyst"))

node_user -->|"starts analysis"| node_home
node_home -.->|"requests data"| node_frontendapi
node_history -->|"loads history"| node_frontendapi
node_frontendapi -.->|"calls graph API"| node_graphapi
node_frontendapi -.->|"calls simulation API"| node_simulationapi
node_frontendapi -.->|"calls report API"| node_reportapi
node_user -->|"submits material"| node_graphapi
node_graphapi -.->|"enriches context"| node_enrichment
node_graphapi -.->|"extracts knowledge"| node_ontology
node_ontology -->|"calls LLM"| node_llm
node_graphapi -.->|"builds graph"| node_graphstore
node_user -->|"configures run"| node_simulationapi
node_simulationapi -->|"prepares simulation"| node_simmanager
node_simmanager -->|"reads entities"| node_entityreader
node_entityreader -->|"queries graph"| node_graphstore
node_simmanager -->|"generates profiles"| node_profiles
node_simmanager -->|"extracts fallback entities"| node_ontology
node_simulationapi -->|"starts run"| node_simrunner
node_simrunner -.->|"records memory"| node_graphstore
node_user -->|"requests report"| node_reportapi
node_reportapi -.->|"checks readiness"| node_reportgate
node_reportapi -.->|"generates analysis"| node_reportagent
node_reportagent -.->|"uses LLM"| node_llm
node_user -->|"converses with agents"| node_helenaapi
node_simulationapi -->|"tracks project"| node_projectstate
node_simmanager -->|"validates storage IDs"| node_safeids
node_simmanager -->|"reads settings"| node_config
node_profiles -->|"reads graph context"| node_graphstore
node_llm -->|"loads provider settings"| node_config
node_simmanager -->|"logs events"| node_logger
node_autoresearch -->|"uses target abstractions"| node_targetbase

click node_home "https://github.com/igormorais123/mirofish/blob/main/frontend/src/views/Home.vue"
click node_history "https://github.com/igormorais123/mirofish/blob/main/frontend/src/components/HistoryDatabase.vue"
click node_frontendapi "https://github.com/igormorais123/mirofish/blob/main/frontend/src/api/index.js"
click node_graphapi "https://github.com/igormorais123/mirofish/blob/main/backend/app/api/graph.py"
click node_enrichment "https://github.com/igormorais123/mirofish/blob/main/backend/app/services/apify_enricher.py"
click node_ontology "https://github.com/igormorais123/mirofish/blob/main/backend/app/services/llm_entity_extractor.py"
click node_graphstore "https://github.com/igormorais123/mirofish/blob/main/backend/app/utils/graphiti_client.py"
click node_simulationapi "https://github.com/igormorais123/mirofish/blob/main/backend/app/api/simulation.py"
click node_profiles "https://github.com/igormorais123/mirofish/blob/main/backend/app/services/oasis_profile_generator.py"
click node_entityreader "https://github.com/igormorais123/mirofish/blob/main/backend/app/services/zep_entity_reader.py"
click node_simmanager "https://github.com/igormorais123/mirofish/blob/main/backend/app/services/simulation_manager.py"
click node_simrunner "https://github.com/igormorais123/mirofish/blob/main/backend/app/services/simulation_runner.py"
click node_projectstate "https://github.com/igormorais123/mirofish/blob/main/backend/app/models/project.py"
click node_reportapi "https://github.com/igormorais123/mirofish/blob/main/backend/app/api/report.py"
click node_reportagent "https://github.com/igormorais123/mirofish/blob/main/backend/app/services/report_agent.py"
click node_reportgate "https://github.com/igormorais123/mirofish/blob/main/backend/app/services/report_system_gate.py"
click node_helenaapi "https://github.com/igormorais123/mirofish/blob/main/backend/app/api/helena.py"
click node_llm "https://github.com/igormorais123/mirofish/blob/main/backend/app/utils/llm_client.py"
click node_config "https://github.com/igormorais123/mirofish/blob/main/backend/app/config.py"
click node_logger "https://github.com/igormorais123/mirofish/blob/main/backend/app/utils/logger.py"
click node_safeids "https://github.com/igormorais123/mirofish/blob/main/backend/app/utils/safe_ids.py"
click node_autoresearch "https://github.com/igormorais123/mirofish/blob/main/backend/autoresearch/engine.py"
click node_targetbase "https://github.com/igormorais123/mirofish/blob/main/backend/autoresearch/targets/base.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_history,node_frontendapi toneBlue
class node_graphapi,node_enrichment,node_ontology,node_graphstore toneAmber
class node_simulationapi,node_profiles,node_entityreader,node_simmanager,node_simrunner toneMint
class node_reportapi,node_reportagent,node_reportgate,node_helenaapi toneRose
class node_projectstate,node_llm,node_config,node_logger,node_safeids,node_autoresearch,node_targetbase,node_user toneIndigo
```

## Components

### User experience

- [Project workspace](https://github.com/igormorais123/mirofish/blob/main/frontend/src/views/Home.vue): `frontend/src/views/Home.vue`
- [Simulation history](https://github.com/igormorais123/mirofish/blob/main/frontend/src/components/HistoryDatabase.vue): `frontend/src/components/HistoryDatabase.vue`
- [Frontend API client](https://github.com/igormorais123/mirofish/blob/main/frontend/src/api/index.js): `frontend/src/api/index.js`

### Knowledge preparation

- [Graph API](https://github.com/igormorais123/mirofish/blob/main/backend/app/api/graph.py): `backend/app/api/graph.py`
- [Web enrichment](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/apify_enricher.py): `backend/app/services/apify_enricher.py`
- [Entity extraction](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/llm_entity_extractor.py): `backend/app/services/llm_entity_extractor.py`
- [Graph memory](https://github.com/igormorais123/mirofish/blob/main/backend/app/utils/graphiti_client.py): `backend/app/utils/graphiti_client.py`

### Simulation runtime

- [Simulation API](https://github.com/igormorais123/mirofish/blob/main/backend/app/api/simulation.py): `backend/app/api/simulation.py`
- [Agent profiles](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/oasis_profile_generator.py): `backend/app/services/oasis_profile_generator.py`
- [Entity reader](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/zep_entity_reader.py): `backend/app/services/zep_entity_reader.py`
- [Simulation manager](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/simulation_manager.py): `backend/app/services/simulation_manager.py`
- [OASIS runner](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/simulation_runner.py): `backend/app/services/simulation_runner.py`

### Reports and analysis

- [Report API](https://github.com/igormorais123/mirofish/blob/main/backend/app/api/report.py): `backend/app/api/report.py`
- [Helena reports](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/report_agent.py): `backend/app/services/report_agent.py`
- [Delivery quality gate](https://github.com/igormorais123/mirofish/blob/main/backend/app/services/report_system_gate.py): `backend/app/services/report_system_gate.py`
- [Helena command API](https://github.com/igormorais123/mirofish/blob/main/backend/app/api/helena.py): `backend/app/api/helena.py`

### Shared platform

- [Project state](https://github.com/igormorais123/mirofish/blob/main/backend/app/models/project.py): `backend/app/models/project.py`
- [LLM client](https://github.com/igormorais123/mirofish/blob/main/backend/app/utils/llm_client.py): `backend/app/utils/llm_client.py`
- [Runtime configuration](https://github.com/igormorais123/mirofish/blob/main/backend/app/config.py): `backend/app/config.py`
- [Structured logging](https://github.com/igormorais123/mirofish/blob/main/backend/app/utils/logger.py): `backend/app/utils/logger.py`
- [Safe identifiers](https://github.com/igormorais123/mirofish/blob/main/backend/app/utils/safe_ids.py): `backend/app/utils/safe_ids.py`
- [Experiment engine](https://github.com/igormorais123/mirofish/blob/main/backend/autoresearch/engine.py): `backend/autoresearch/engine.py`
- [Research targets](https://github.com/igormorais123/mirofish/blob/main/backend/autoresearch/targets/base.py): `backend/autoresearch/targets/base.py`

### Other components

- **Analyst**

## Connections

- Analyst → Project workspace: starts analysis (evidence: `README.md`)
- Project workspace → Frontend API client: requests data
- Simulation history → Frontend API client: loads history (evidence: `frontend/src/components/HistoryDatabase.vue`)
- Frontend API client → Graph API: calls graph API
- Frontend API client → Simulation API: calls simulation API
- Frontend API client → Report API: calls report API
- Analyst → Graph API: submits material (evidence: `README.md`)
- Graph API → Web enrichment: enriches context (evidence: `README.md`)
- Graph API → Entity extraction: extracts knowledge (evidence: `README.md`)
- Entity extraction → LLM client: calls LLM (evidence: `backend/app/services/llm_entity_extractor.py`)
- Graph API → Graph memory: builds graph (evidence: `README.md`)
- Analyst → Simulation API: configures run (evidence: `README.md`)
- Simulation API → Simulation manager: prepares simulation (evidence: `backend/app/api/simulation.py`)
- Simulation manager → Entity reader: reads entities (evidence: `backend/app/services/simulation_manager.py`)
- Entity reader → Graph memory: queries graph (evidence: `backend/app/services/zep_entity_reader.py`)
- Simulation manager → Agent profiles: generates profiles (evidence: `backend/app/services/simulation_manager.py`)
- Simulation manager → Entity extraction: extracts fallback entities (evidence: `backend/app/services/simulation_manager.py`)
- Simulation API → OASIS runner: starts run (evidence: `backend/app/api/simulation.py`)
- OASIS runner → Graph memory: records memory
- Analyst → Report API: requests report (evidence: `README.md`)
- Report API → Delivery quality gate: checks readiness (evidence: `README.md`)
- Report API → Helena reports: generates analysis (evidence: `README.md`)
- Helena reports → LLM client: uses LLM
- Analyst → Helena command API: converses with agents (evidence: `README.md`)
- Simulation API → Project state: tracks project (evidence: `backend/app/api/simulation.py`)
- Simulation manager → Safe identifiers: validates storage IDs (evidence: `backend/app/services/simulation_manager.py`)
- Simulation manager → Runtime configuration: reads settings (evidence: `backend/app/services/simulation_manager.py`)
- Agent profiles → Graph memory: reads graph context (evidence: `backend/app/services/oasis_profile_generator.py`)
- LLM client → Runtime configuration: loads provider settings (evidence: `backend/app/utils/llm_client.py`)
- Simulation manager → Structured logging: logs events (evidence: `backend/app/services/simulation_manager.py`)
- Experiment engine → Research targets: uses target abstractions (evidence: `backend/autoresearch/engine.py`)
