# luisff73/cargadores architecture

> Architecture diagram of the GitHub repository luisff73/cargadores, 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/luisff73/cargadores
- Repository: https://github.com/luisff73/cargadores

## Overview

This repository provides a Spanish EV-charger search service with Iberdrola and Feníe data, plus availability monitoring and Telegram alerts. The main web workflow accepts a locality, geocodes it, searches Iberdrola chargers, checks live availability, normalizes and sorts results, and returns them through FastAPI. Feníe has a separate catalog-backed search and monitoring route; tariff collection is another capability. Some API implementation is excerpted only partially, so the graph omits unverified internal calls.

Main entry points: [`api/cargadores.py`](https://github.com/luisff73/cargadores/blob/main/api/cargadores.py) (API routes), [`api/fenie.py`](https://github.com/luisff73/cargadores/blob/main/api/fenie.py) (Feníe routes), [`vigilancia.py`](https://github.com/luisff73/cargadores/blob/main/vigilancia.py) (Watch engine), [`coordenadas_fenie.py`](https://github.com/luisff73/cargadores/blob/main/coordenadas_fenie.py) (Catalog enrichment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web API"]
  node_frontend["Search interface<br/>[index.html]"]
  node_api["API routes<br/>[cargadores.py]"]
  node_entry["App entry<br/>[main.py]"]
end

subgraph group_iberdrola["Iberdrola Search"]
  node_geocode["Geocoding<br/>[buscador.py]"]
  node_charger_search["Charger search<br/>[buscador.py]"]
  node_availability["Live availability<br/>[buscador.py]"]
  node_normalize["Result shaping<br/>[buscador.py]"]
end

subgraph group_fenie["Feníe Services"]
  node_fenie_api["Feníe routes<br/>[fenie.py]"]
  node_catalog[("Feníe catalog")]
  node_tariffs["Tariff collection<br/>[tarifas_fenie.py]"]
  node_catalog_scan["Catalog enrichment"]
  node_scan_archive[("Scan archive<br/>[fenie_barrido.json]")]
end

subgraph group_monitor["Availability Monitoring"]
  node_watch_api["Watch endpoints<br/>[cargadores.py]"]
  node_watch_engine["Watch engine<br/>[vigilancia.py]"]
  node_bot["Polling bot<br/>[bot.py]"]
end

node_user(("Search user"))
node_telegram["Telegram"]
node_iberdrola_service["Iberdrola service"]
node_fenie_service["Feníe service"]

node_user -.->|"uses"| node_frontend
node_frontend -.->|"requests"| node_api
node_entry -->|"exports app"| node_api
node_api -->|"geocodes"| node_geocode
node_api -->|"searches"| node_charger_search
node_api -->|"checks"| node_availability
node_api -->|"normalizes"| node_normalize
node_geocode -->|"queries"| node_iberdrola_service
node_charger_search -->|"queries"| node_iberdrola_service
node_availability -->|"queries"| node_iberdrola_service
node_api -->|"mounts router"| node_fenie_api
node_fenie_api -->|"reads"| node_catalog
node_fenie_api -->|"checks status"| node_fenie_service
node_tariffs -->|"fetches tariffs"| node_fenie_service
node_catalog_scan -->|"reads"| node_scan_archive
node_catalog_scan -->|"updates coordinates"| node_catalog
node_api -->|"accepts watch requests"| node_watch_api
node_watch_api -->|"starts watch"| node_watch_engine
node_fenie_api -->|"starts watch"| node_watch_engine
node_watch_engine -->|"checks chargers"| node_iberdrola_service
node_watch_engine -->|"sends alerts"| node_telegram
node_bot -->|"polls status"| node_iberdrola_service
node_bot -->|"sends alerts"| node_telegram

click node_frontend "https://github.com/luisff73/cargadores/blob/main/public/index.html"
click node_api "https://github.com/luisff73/cargadores/blob/main/api/cargadores.py"
click node_entry "https://github.com/luisff73/cargadores/blob/main/main.py"
click node_geocode "https://github.com/luisff73/cargadores/blob/main/buscador.py"
click node_charger_search "https://github.com/luisff73/cargadores/blob/main/buscador.py"
click node_availability "https://github.com/luisff73/cargadores/blob/main/buscador.py"
click node_normalize "https://github.com/luisff73/cargadores/blob/main/buscador.py"
click node_fenie_api "https://github.com/luisff73/cargadores/blob/main/api/fenie.py"
click node_catalog "https://github.com/luisff73/cargadores/blob/main/fenie_catalogo_completo.json"
click node_tariffs "https://github.com/luisff73/cargadores/blob/main/tarifas_fenie.py"
click node_catalog_scan "https://github.com/luisff73/cargadores/blob/main/coordenadas_fenie.py"
click node_scan_archive "https://github.com/luisff73/cargadores/blob/main/fenie_barrido.json"
click node_watch_api "https://github.com/luisff73/cargadores/blob/main/api/cargadores.py"
click node_watch_engine "https://github.com/luisff73/cargadores/blob/main/vigilancia.py"
click node_bot "https://github.com/luisff73/cargadores/blob/main/bot.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_frontend,node_api,node_entry,node_user toneBlue
class node_geocode,node_charger_search,node_availability,node_normalize toneAmber
class node_fenie_api,node_catalog,node_tariffs,node_catalog_scan,node_scan_archive toneMint
class node_watch_api,node_watch_engine,node_bot toneRose
class node_telegram,node_iberdrola_service,node_fenie_service toneIndigo
```

## Components

### Web API

- [Search interface](https://github.com/luisff73/cargadores/blob/main/public/index.html): `public/index.html`
- [API routes](https://github.com/luisff73/cargadores/blob/main/api/cargadores.py): `api/cargadores.py`
- [App entry](https://github.com/luisff73/cargadores/blob/main/main.py): `main.py`

### Iberdrola Search

- [Geocoding](https://github.com/luisff73/cargadores/blob/main/buscador.py): `buscador.py`
- [Charger search](https://github.com/luisff73/cargadores/blob/main/buscador.py): `buscador.py`
- [Live availability](https://github.com/luisff73/cargadores/blob/main/buscador.py): `buscador.py`
- [Result shaping](https://github.com/luisff73/cargadores/blob/main/buscador.py): `buscador.py`

### Feníe Services

- [Feníe routes](https://github.com/luisff73/cargadores/blob/main/api/fenie.py): `api/fenie.py`
- [Feníe catalog](https://github.com/luisff73/cargadores/blob/main/fenie_catalogo_completo.json): `fenie_catalogo_completo.json`
- [Tariff collection](https://github.com/luisff73/cargadores/blob/main/tarifas_fenie.py): `tarifas_fenie.py`
- [Catalog enrichment](https://github.com/luisff73/cargadores/blob/main/coordenadas_fenie.py): `coordenadas_fenie.py`
- [Scan archive](https://github.com/luisff73/cargadores/blob/main/fenie_barrido.json): `fenie_barrido.json`

### Availability Monitoring

- [Watch endpoints](https://github.com/luisff73/cargadores/blob/main/api/cargadores.py): `api/cargadores.py`
- [Watch engine](https://github.com/luisff73/cargadores/blob/main/vigilancia.py): `vigilancia.py`
- [Polling bot](https://github.com/luisff73/cargadores/blob/main/bot.py): `bot.py`

### Other components

- **Search user**
- **Telegram**
- **Iberdrola service**
- **Feníe service**

## Connections

- Search user → Search interface: uses
- Search interface → API routes: requests
- App entry → API routes: exports app (evidence: `main.py`)
- API routes → Geocoding: geocodes (evidence: `api/cargadores.py`)
- API routes → Charger search: searches (evidence: `api/cargadores.py`)
- API routes → Live availability: checks (evidence: `api/cargadores.py`)
- API routes → Result shaping: normalizes (evidence: `api/cargadores.py`)
- Geocoding → Iberdrola service: queries (evidence: `buscador.py`)
- Charger search → Iberdrola service: queries (evidence: `buscador.py`)
- Live availability → Iberdrola service: queries (evidence: `buscador.py`)
- API routes → Feníe routes: mounts router (evidence: `api/cargadores.py`)
- Feníe routes → Feníe catalog: reads (evidence: `api/fenie.py`)
- Feníe routes → Feníe service: checks status (evidence: `api/fenie.py`)
- Tariff collection → Feníe service: fetches tariffs (evidence: `tarifas_fenie.py`)
- Catalog enrichment → Scan archive: reads (evidence: `coordenadas_fenie.py`)
- Catalog enrichment → Feníe catalog: updates coordinates (evidence: `coordenadas_fenie.py`)
- API routes → Watch endpoints: accepts watch requests (evidence: `api/cargadores.py`)
- Watch endpoints → Watch engine: starts watch (evidence: `api/cargadores.py`)
- Feníe routes → Watch engine: starts watch (evidence: `api/fenie.py`)
- Watch engine → Iberdrola service: checks chargers (evidence: `vigilancia.py`)
- Watch engine → Telegram: sends alerts (evidence: `vigilancia.py`)
- Polling bot → Iberdrola service: polls status (evidence: `bot.py`)
- Polling bot → Telegram: sends alerts (evidence: `bot.py`)