# equipo5-aqp/healthradar architecture

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

- Interactive diagram: https://gitdiagram.com/equipo5-aqp/healthradar
- Repository: https://github.com/equipo5-aqp/healthradar

## Overview

HealthRadar is a Peruvian epidemiological-surveillance system. Analysts use separate consulta and históricos microfrontends: natural-language questions produce analytical reports and trends, while historical views expose filtered data. The README documents n8n as the sole logic orchestrator, with PostgreSQL/pgvector, external AI and weather services, and a weekly MINSA bulletin-ingestion workflow. The graph includes the sampled core decision library and frontend adapters; ingestion internals and n8n workflows are documented capabilities, but their implementation files are not in the supplied tree.

Main entry points: [`src/core/index.js`](https://github.com/equipo5-aqp/healthradar/blob/main/src/core/index.js) (Core exports), [`src/mf-consulta/src/modules/consulta/infrastructure/n8nConsultaAdapter.js`](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/modules/consulta/infrastructure/n8nConsultaAdapter.js) (Consulta adapter), [`src/mf-consulta/src/app/api/consulta/route.js`](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/app/api/consulta/route.js) (Consulta API), [`src/mf-consulta/src/app/api/tendencia/route.js`](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/app/api/tendencia/route.js) (Trend API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_users["User interfaces"]
  node_consulta["Consulta UI<br/>[page.js]"]
  node_consulta_hooks["Consulta hooks<br/>[useConsultaNLQ.js]"]
  node_consulta_adapter["Consulta adapter"]
  node_consulta_api["Consulta API<br/>[route.js]"]
  node_trend_api["Trend API<br/>[route.js]"]
  node_trend_hook["Trend hook<br/>[useTendencia.js]"]
  node_history_ui["History UI<br/>[page.js]"]
  node_history_hook["History hook<br/>[useHistoricos.js]"]
  node_history_adapter["History adapter"]
  node_history_api["History API<br/>[route.js]"]
end

subgraph group_core["Decision core"]
  node_core_api["Core exports<br/>[index.js]"]
  node_parsers["Query parsers"]
  node_prediction["Prediction decision"]
  node_bulletin_filter["Bulletin filter<br/>[boletines.js]"]
  node_climate_filter["Climate filter<br/>[clima.js]"]
  node_context_builder["Prompt context<br/>[contexto-prompt.js]"]
  node_trend_builder["Trend builder<br/>[tendencia.js]"]
  node_bulletin_validator["Bulletin validator<br/>[resumen-boletin.js]"]
  node_presentation["Presentation rules"]
end

subgraph group_ingestion["Data ingestion"]
  node_minsa["MINSA / CDC"]
  node_meteo["Open-Meteo"]
  node_gemini["Gemini Flash"]
  node_db_load["MINSA data loader"]
  node_db_clean["Dataset cleaning"]
end

subgraph group_services["Orchestration and services"]
  node_n8n{{"n8n orchestrator"}}
  node_postgres[("PostgreSQL + pgvector")]
  node_claude["Claude Haiku"]
  node_phoenix["Arize Phoenix"]
end

node_analyst(("Health analyst"))

node_analyst -->|"asks questions"| node_consulta
node_analyst -->|"views history"| node_history_ui
node_consulta_hooks -->|"calls"| node_consulta_adapter
node_consulta_adapter -->|"posts query"| node_consulta_api
node_trend_hook -->|"loads trends"| node_consulta_adapter
node_consulta_adapter -->|"posts trend request"| node_trend_api
node_history_hook -->|"loads history"| node_history_adapter
node_history_adapter -.->|"requests history"| node_history_api
node_consulta_api -->|"proxies query"| node_n8n
node_trend_api -->|"proxies trend"| node_n8n
node_history_api -->|"proxies history"| node_n8n
node_n8n -->|"uses core"| node_core_api
node_core_api -->|"exports parsers"| node_parsers
node_core_api -->|"exports decision"| node_prediction
node_core_api -->|"exports filter"| node_bulletin_filter
node_core_api -->|"exports filter"| node_climate_filter
node_core_api -->|"exports builder"| node_context_builder
node_core_api -->|"exports builder"| node_trend_builder
node_core_api -->|"exports validator"| node_bulletin_validator
node_core_api -->|"exports rules"| node_presentation
node_n8n -->|"queries and writes"| node_postgres
node_n8n -->|"requests reports"| node_claude
node_n8n -->|"sends traces"| node_phoenix
node_n8n -->|"downloads bulletins"| node_minsa
node_n8n -->|"fetches climate"| node_meteo
node_n8n -->|"extracts bulletin data"| node_gemini
node_n8n -->|"stores ingested data"| node_postgres

click node_consulta "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/app/page.js"
click node_consulta_hooks "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/modules/consulta/hooks/useConsultaNLQ.js"
click node_consulta_adapter "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/modules/consulta/infrastructure/n8nConsultaAdapter.js"
click node_consulta_api "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/app/api/consulta/route.js"
click node_trend_api "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/app/api/tendencia/route.js"
click node_trend_hook "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/modules/consulta/hooks/useTendencia.js"
click node_history_ui "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-historicos/src/app/page.js"
click node_history_hook "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-historicos/src/modules/historicos/hooks/useHistoricos.js"
click node_history_adapter "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-historicos/src/modules/historicos/infrastructure/n8nHistoricosAdapter.js"
click node_history_api "https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-historicos/src/app/api/historicos/route.js"
click node_core_api "https://github.com/equipo5-aqp/healthradar/blob/main/src/core/index.js"
click node_parsers "https://github.com/equipo5-aqp/healthradar/tree/main/src/core/parsers"
click node_prediction "https://github.com/equipo5-aqp/healthradar/blob/main/src/core/decisions/activar-prediccion.js"
click node_bulletin_filter "https://github.com/equipo5-aqp/healthradar/blob/main/src/core/filters/boletines.js"
click node_climate_filter "https://github.com/equipo5-aqp/healthradar/blob/main/src/core/filters/clima.js"
click node_context_builder "https://github.com/equipo5-aqp/healthradar/blob/main/src/core/builders/contexto-prompt.js"
click node_trend_builder "https://github.com/equipo5-aqp/healthradar/blob/main/src/core/builders/tendencia.js"
click node_bulletin_validator "https://github.com/equipo5-aqp/healthradar/blob/main/src/core/validators/resumen-boletin.js"
click node_presentation "https://github.com/equipo5-aqp/healthradar/tree/main/src/core/presentacion"
click node_db_load "https://github.com/equipo5-aqp/healthradar/blob/main/src/database/cargar_datos_minsa.py"
click node_db_clean "https://github.com/equipo5-aqp/healthradar/blob/main/src/database/limpiar_datasets_minsa.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_consulta,node_consulta_hooks,node_consulta_adapter,node_consulta_api,node_trend_api,node_trend_hook,node_history_ui,node_history_hook,node_history_adapter,node_history_api toneBlue
class node_core_api,node_parsers,node_prediction,node_bulletin_filter,node_climate_filter,node_context_builder,node_trend_builder,node_bulletin_validator,node_presentation toneAmber
class node_minsa,node_meteo,node_gemini,node_db_load,node_db_clean toneMint
class node_n8n,node_postgres,node_claude,node_phoenix toneRose
class node_analyst toneIndigo
```

## Components

### User interfaces

- [Consulta UI](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/app/page.js): `src/mf-consulta/src/app/page.js`
- [Consulta hooks](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/modules/consulta/hooks/useConsultaNLQ.js): `src/mf-consulta/src/modules/consulta/hooks/useConsultaNLQ.js`
- [Consulta adapter](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/modules/consulta/infrastructure/n8nConsultaAdapter.js): `src/mf-consulta/src/modules/consulta/infrastructure/n8nConsultaAdapter.js`
- [Consulta API](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/app/api/consulta/route.js): `src/mf-consulta/src/app/api/consulta/route.js`
- [Trend API](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/app/api/tendencia/route.js): `src/mf-consulta/src/app/api/tendencia/route.js`
- [Trend hook](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-consulta/src/modules/consulta/hooks/useTendencia.js): `src/mf-consulta/src/modules/consulta/hooks/useTendencia.js`
- [History UI](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-historicos/src/app/page.js): `src/mf-historicos/src/app/page.js`
- [History hook](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-historicos/src/modules/historicos/hooks/useHistoricos.js): `src/mf-historicos/src/modules/historicos/hooks/useHistoricos.js`
- [History adapter](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-historicos/src/modules/historicos/infrastructure/n8nHistoricosAdapter.js): `src/mf-historicos/src/modules/historicos/infrastructure/n8nHistoricosAdapter.js`
- [History API](https://github.com/equipo5-aqp/healthradar/blob/main/src/mf-historicos/src/app/api/historicos/route.js): `src/mf-historicos/src/app/api/historicos/route.js`

### Decision core

- [Core exports](https://github.com/equipo5-aqp/healthradar/blob/main/src/core/index.js): `src/core/index.js`
- [Query parsers](https://github.com/equipo5-aqp/healthradar/tree/main/src/core/parsers): `src/core/parsers`
- [Prediction decision](https://github.com/equipo5-aqp/healthradar/blob/main/src/core/decisions/activar-prediccion.js): `src/core/decisions/activar-prediccion.js`
- [Bulletin filter](https://github.com/equipo5-aqp/healthradar/blob/main/src/core/filters/boletines.js): `src/core/filters/boletines.js`
- [Climate filter](https://github.com/equipo5-aqp/healthradar/blob/main/src/core/filters/clima.js): `src/core/filters/clima.js`
- [Prompt context](https://github.com/equipo5-aqp/healthradar/blob/main/src/core/builders/contexto-prompt.js): `src/core/builders/contexto-prompt.js`
- [Trend builder](https://github.com/equipo5-aqp/healthradar/blob/main/src/core/builders/tendencia.js): `src/core/builders/tendencia.js`
- [Bulletin validator](https://github.com/equipo5-aqp/healthradar/blob/main/src/core/validators/resumen-boletin.js): `src/core/validators/resumen-boletin.js`
- [Presentation rules](https://github.com/equipo5-aqp/healthradar/tree/main/src/core/presentacion): `src/core/presentacion`

### Data ingestion

- **MINSA / CDC**
- **Open-Meteo**
- **Gemini Flash**
- [MINSA data loader](https://github.com/equipo5-aqp/healthradar/blob/main/src/database/cargar_datos_minsa.py): `src/database/cargar_datos_minsa.py`
- [Dataset cleaning](https://github.com/equipo5-aqp/healthradar/blob/main/src/database/limpiar_datasets_minsa.py): `src/database/limpiar_datasets_minsa.py`

### Orchestration and services

- **n8n orchestrator**
- **PostgreSQL + pgvector**
- **Claude Haiku**
- **Arize Phoenix**

### Other components

- **Health analyst**

## Connections

- Health analyst → Consulta UI: asks questions
- Health analyst → History UI: views history
- Consulta hooks → Consulta adapter: calls (evidence: `src/mf-consulta/src/modules/consulta/hooks/useConsultaNLQ.js`)
- Consulta adapter → Consulta API: posts query (evidence: `src/mf-consulta/src/modules/consulta/infrastructure/n8nConsultaAdapter.js`)
- Trend hook → Consulta adapter: loads trends (evidence: `src/mf-consulta/src/modules/consulta/hooks/useTendencia.js`)
- Consulta adapter → Trend API: posts trend request (evidence: `src/mf-consulta/src/modules/consulta/infrastructure/n8nConsultaAdapter.js`)
- History hook → History adapter: loads history (evidence: `src/mf-historicos/src/modules/historicos/hooks/useHistoricos.js`)
- History adapter → History API: requests history
- Consulta API → n8n orchestrator: proxies query
- Trend API → n8n orchestrator: proxies trend
- History API → n8n orchestrator: proxies history
- n8n orchestrator → Core exports: uses core (evidence: `src/core/index.js`)
- Core exports → Query parsers: exports parsers (evidence: `src/core/index.js`)
- Core exports → Prediction decision: exports decision (evidence: `src/core/index.js`)
- Core exports → Bulletin filter: exports filter (evidence: `src/core/index.js`)
- Core exports → Climate filter: exports filter (evidence: `src/core/index.js`)
- Core exports → Prompt context: exports builder (evidence: `src/core/index.js`)
- Core exports → Trend builder: exports builder (evidence: `src/core/index.js`)
- Core exports → Bulletin validator: exports validator (evidence: `src/core/index.js`)
- Core exports → Presentation rules: exports rules (evidence: `src/core/index.js`)
- n8n orchestrator → PostgreSQL + pgvector: queries and writes
- n8n orchestrator → Claude Haiku: requests reports
- n8n orchestrator → Arize Phoenix: sends traces
- n8n orchestrator → MINSA / CDC: downloads bulletins
- n8n orchestrator → Open-Meteo: fetches climate
- n8n orchestrator → Gemini Flash: extracts bulletin data
- n8n orchestrator → PostgreSQL + pgvector: stores ingested data
