# kitagrasa/evaca-centinela architecture

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

- Interactive diagram: https://gitdiagram.com/kitagrasa/evaca-centinela
- Repository: https://github.com/kitagrasa/evaca-centinela

## Overview

This Python CLI monitors public eVaca portfolios and also produces indexed performance series for Portfolio Performance. The check workflow loads configuration and watchlists, fetches portfolio snapshots, compares positions with saved state, then formats and optionally sends alerts. The separate series workflow coordinates data acquisition, pure calculation, output formatting, and persisted results. The source index and excerpts support these principal calls; the README is empty, so other workflow details are not inferred.

Main entry points: [`evaca_monitor/monitor.py`](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/monitor.py) (Monitor orchestration), [`evaca_monitor/cli.py`](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/cli.py) (CLI commands), [`evaca_monitor/serie_run.py`](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie_run.py) (Series orchestration), [`evaca_monitor/config.py`](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/config.py) (Configuration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and configuration"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_watchlist["Followed users<br/>[watchlist.py]"]
  node_schedule["Schedule rules<br/>[schedule.py]"]
end

subgraph group_monitoring["Portfolio monitoring"]
  node_monitor["Monitor orchestration<br/>[monitor.py]"]
  node_models["Portfolio models<br/>[models.py]"]
  node_diff["Position comparison<br/>[diff.py]"]
  node_render["Alert rendering<br/>[render.py]"]
  node_history["Historical operations<br/>[historial.py]"]
end

subgraph group_series["Performance series"]
  node_series_run["Series orchestration<br/>[serie_run.py]"]
  node_series_calc["Series calculations<br/>[serie.py]"]
  node_series_html["Series HTML output<br/>[serie_html.py]"]
end

subgraph group_persistence["State and outputs"]
  node_state[("Portfolio state<br/>[state.py]")]
  node_cooldown[("Alert cooldown<br/>[cooldown.py]")]
  node_statefiles[("State files")]
  node_series_store["Series storage<br/>[serie_store.py]"]
  node_seriesfiles[("Series data files")]
end

subgraph group_integrations["External services"]
  node_client["eVaca client<br/>[client.py]"]
  node_telegram["Telegram notifier<br/>[telegram.py]"]
end

node_operator(("Operator"))
node_evaca{{"Public eVaca API"}}
node_telegram_service{{"Telegram"}}

node_operator -->|"runs commands"| node_cli
node_cli -->|"loads settings"| node_config
node_config -->|"loads users"| node_watchlist
node_config -->|"parses rules"| node_schedule
node_cli -->|"runs checks"| node_monitor
node_monitor -->|"fetches portfolios"| node_client
node_client -->|"requests public data"| node_evaca
node_monitor -->|"builds snapshots"| node_models
node_monitor -->|"compares snapshots"| node_diff
node_monitor -->|"loads and saves"| node_state
node_state -->|"persists"| node_statefiles
node_monitor -->|"checks history"| node_history
node_monitor -->|"formats alerts"| node_render
node_monitor -->|"checks cooldown"| node_cooldown
node_cooldown -->|"persists"| node_statefiles
node_cli -->|"configures notifier"| node_telegram
node_telegram -.->|"sends messages"| node_telegram_service
node_cli -->|"runs series"| node_series_run
node_series_run -->|"fetches source data"| node_client
node_series_run -->|"calculates returns"| node_series_calc
node_series_run -->|"formats output"| node_series_html
node_series_run -->|"reads and writes"| node_series_store
node_series_store -.->|"persists series"| node_seriesfiles

click node_cli "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/cli.py"
click node_config "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/config.py"
click node_watchlist "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/watchlist.py"
click node_schedule "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/schedule.py"
click node_monitor "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/monitor.py"
click node_client "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/client.py"
click node_models "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/models.py"
click node_diff "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/diff.py"
click node_render "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/render.py"
click node_history "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/historial.py"
click node_state "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/state.py"
click node_cooldown "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/cooldown.py"
click node_statefiles "https://github.com/kitagrasa/evaca-centinela/tree/main/state"
click node_telegram "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/telegram.py"
click node_series_run "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie_run.py"
click node_series_calc "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie.py"
click node_series_html "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie_html.py"
click node_series_store "https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie_store.py"
click node_seriesfiles "https://github.com/kitagrasa/evaca-centinela/tree/main/data/series"

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_cli,node_config,node_watchlist,node_schedule toneBlue
class node_monitor,node_models,node_diff,node_render,node_history toneAmber
class node_series_run,node_series_calc,node_series_html,node_evaca toneMint
class node_state,node_cooldown,node_statefiles,node_series_store,node_seriesfiles toneRose
class node_client,node_telegram,node_operator,node_telegram_service toneIndigo
```

## Components

### CLI and configuration

- [CLI commands](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/cli.py): `evaca_monitor/cli.py`
- [Configuration](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/config.py): `evaca_monitor/config.py`
- [Followed users](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/watchlist.py): `evaca_monitor/watchlist.py`
- [Schedule rules](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/schedule.py): `evaca_monitor/schedule.py`

### Portfolio monitoring

- [Monitor orchestration](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/monitor.py): `evaca_monitor/monitor.py`
- [Portfolio models](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/models.py): `evaca_monitor/models.py`
- [Position comparison](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/diff.py): `evaca_monitor/diff.py`
- [Alert rendering](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/render.py): `evaca_monitor/render.py`
- [Historical operations](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/historial.py): `evaca_monitor/historial.py`

### Performance series

- [Series orchestration](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie_run.py): `evaca_monitor/serie_run.py`
- [Series calculations](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie.py): `evaca_monitor/serie.py`
- [Series HTML output](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie_html.py): `evaca_monitor/serie_html.py`

### State and outputs

- [Portfolio state](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/state.py): `evaca_monitor/state.py`
- [Alert cooldown](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/cooldown.py): `evaca_monitor/cooldown.py`
- [State files](https://github.com/kitagrasa/evaca-centinela/tree/main/state): `state`
- [Series storage](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/serie_store.py): `evaca_monitor/serie_store.py`
- [Series data files](https://github.com/kitagrasa/evaca-centinela/tree/main/data/series): `data/series`

### External services

- [eVaca client](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/client.py): `evaca_monitor/client.py`
- [Telegram notifier](https://github.com/kitagrasa/evaca-centinela/blob/main/evaca_monitor/telegram.py): `evaca_monitor/telegram.py`

### Other components

- **Operator**
- **Public eVaca API**
- **Telegram**

## Connections

- Operator → CLI commands: runs commands (evidence: `evaca_monitor/cli.py`)
- CLI commands → Configuration: loads settings (evidence: `evaca_monitor/cli.py`)
- Configuration → Followed users: loads users (evidence: `evaca_monitor/config.py`)
- Configuration → Schedule rules: parses rules (evidence: `evaca_monitor/config.py`)
- CLI commands → Monitor orchestration: runs checks (evidence: `evaca_monitor/cli.py`)
- Monitor orchestration → eVaca client: fetches portfolios (evidence: `evaca_monitor/monitor.py`)
- eVaca client → Public eVaca API: requests public data (evidence: `evaca_monitor/client.py`)
- Monitor orchestration → Portfolio models: builds snapshots (evidence: `evaca_monitor/monitor.py`)
- Monitor orchestration → Position comparison: compares snapshots (evidence: `evaca_monitor/monitor.py`)
- Monitor orchestration → Portfolio state: loads and saves (evidence: `evaca_monitor/monitor.py`)
- Portfolio state → State files: persists (evidence: `evaca_monitor/state.py`)
- Monitor orchestration → Historical operations: checks history (evidence: `evaca_monitor/monitor.py`)
- Monitor orchestration → Alert rendering: formats alerts (evidence: `evaca_monitor/monitor.py`)
- Monitor orchestration → Alert cooldown: checks cooldown (evidence: `evaca_monitor/monitor.py`)
- Alert cooldown → State files: persists (evidence: `evaca_monitor/cooldown.py`)
- CLI commands → Telegram notifier: configures notifier (evidence: `evaca_monitor/cli.py`)
- Telegram notifier → Telegram: sends messages
- CLI commands → Series orchestration: runs series (evidence: `evaca_monitor/cli.py`)
- Series orchestration → eVaca client: fetches source data (evidence: `evaca_monitor/serie_run.py`)
- Series orchestration → Series calculations: calculates returns (evidence: `evaca_monitor/serie_run.py`)
- Series orchestration → Series HTML output: formats output (evidence: `evaca_monitor/serie_run.py`)
- Series orchestration → Series storage: reads and writes (evidence: `evaca_monitor/serie_run.py`)
- Series storage → Series data files: persists series