# barretopalacios/sistema-de-consulta-ruc-sunat architecture

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

- Interactive diagram: https://gitdiagram.com/barretopalacios/sistema-de-consulta-ruc-sunat
- Repository: https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat

## Overview

Sistema de consulta del padrón reducido de contribuyentes SUNAT: la API y la Web UI reciben consultas por RUC, que se validan y resuelven mediante caché o SQLite. En paralelo, el CLI actualiza el padrón con detección de cambios, descarga, extracción, parseo, carga, indexación y publicación atómica; la API lee la base publicada y la Web UI también muestra estadísticas y estado de actualización. Las rutas principales y los servicios centrales están respaldados por código muestreado; capacidades de API documentadas sin flujo muestreado se representan con conexiones conservadoras.

Main entry points: [`apps/updater/services/update_service.py`](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/update_service.py) (Coordinador actualización), [`apps/api/app/api/ruc/service.py`](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.py) (Servicio RUC), [`apps/api/app/api/ruc/router.py`](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/router.py) (Rutas RUC), [`apps/api/app/web/routes.py`](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/web/routes.py) (Rutas web)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API y acceso"]
  node_api_entry["Aplicación FastAPI<br/>[main.py]"]
  node_api_router["Rutas RUC<br/>[router.py]"]
  node_auth["Autenticación<br/>[security.py]"]
  node_ruc_service["Servicio RUC<br/>[service.py]"]
  node_cache["Caché TTL<br/>[service.py]"]
  node_export["Exportación<br/>[service.py]"]
  node_statistics["Estadísticas y estado<br/>[service.py]"]
end

subgraph group_web["Interfaz web"]
  node_web_routes["Rutas web<br/>[routes.py]"]
  node_web_templates["Plantillas UI"]
end

subgraph group_updater["Actualizador padrón"]
  node_updater_cli["CLI actualizador<br/>[main.py]"]
  node_update_service["Coordinador actualización<br/>[update_service.py]"]
  node_download["Descarga y cambios"]
  node_extract["Extracción TXT<br/>[extract_service.py]"]
  node_load["Carga padrón<br/>[load_service.py]"]
  node_parse["Parseo de líneas<br/>[parse_service.py]"]
  node_index["Creación índices<br/>[index_service.py]"]
  node_publish["Publicación atómica<br/>[publish_service.py]"]
end

subgraph group_shared["Servicios compartidos"]
  node_database[("Base contribuyentes")]
  node_db_connection["Conexión SQLite<br/>[connection.py]"]
  node_metadata["Metadatos actualización"]
  node_encoding["Detección codificación<br/>[encodings.py]"]
  node_sqlite_helpers["Operaciones SQLite<br/>[sqlite.py]"]
end

node_user(("Usuario"))
node_sunat["Fuente ZIP SUNAT"]

node_user -->|"solicita API"| node_api_entry
node_api_entry -->|"dirige rutas"| node_api_router
node_api_router -->|"verifica token"| node_auth
node_api_router -->|"consulta y exporta"| node_ruc_service
node_ruc_service -->|"lee y escribe"| node_cache
node_ruc_service -->|"abre conexión"| node_db_connection
node_db_connection -->|"lee SQLite"| node_database
node_user -->|"busca en web"| node_web_routes
node_web_routes -->|"consulta RUC"| node_ruc_service
node_web_routes -->|"renderiza páginas"| node_web_templates
node_web_routes -->|"lee estado"| node_metadata
node_ruc_service -->|"calcula métricas"| node_statistics
node_api_router -->|"solicita métricas"| node_statistics
node_api_router -->|"solicita exportación"| node_export
node_user -->|"ejecuta CLI"| node_updater_cli
node_updater_cli -->|"inicia actualización"| node_update_service
node_updater_cli -->|"comprueba cambios"| node_download
node_update_service -->|"comprueba y descarga"| node_download
node_download -->|"consulta y descarga"| node_sunat
node_download -->|"lee y guarda"| node_metadata
node_update_service -->|"extrae TXT"| node_extract
node_update_service -->|"carga registros"| node_load
node_load -->|"parsea líneas"| node_parse
node_load -->|"detecta codificación"| node_encoding
node_load -->|"inserta lotes"| node_sqlite_helpers
node_update_service -->|"crea índices"| node_index
node_update_service -->|"valida y publica"| node_publish
node_publish -->|"reemplaza base activa"| node_database
node_web_routes -->|"consulta estadísticas"| node_ruc_service

click node_api_entry "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/main.py"
click node_api_router "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/router.py"
click node_auth "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/core/security.py"
click node_ruc_service "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.py"
click node_cache "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.py"
click node_database "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/tree/main/data"
click node_db_connection "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/packages/database/connection.py"
click node_web_routes "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/web/routes.py"
click node_web_templates "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/tree/main/apps/api/app/web"
click node_metadata "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/tree/main/data"
click node_updater_cli "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/main.py"
click node_update_service "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/update_service.py"
click node_download "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/download_service.py"
click node_extract "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/extract_service.py"
click node_load "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/load_service.py"
click node_parse "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/parse_service.py"
click node_encoding "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/packages/utils/encodings.py"
click node_sqlite_helpers "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/packages/database/sqlite.py"
click node_index "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/index_service.py"
click node_publish "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/publish_service.py"
click node_export "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.py"
click node_statistics "https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.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_api_entry,node_api_router,node_auth,node_ruc_service,node_cache,node_export,node_statistics toneBlue
class node_web_routes,node_web_templates toneAmber
class node_updater_cli,node_update_service,node_download,node_extract,node_load,node_parse,node_index,node_publish toneMint
class node_database,node_db_connection,node_metadata,node_encoding,node_sqlite_helpers toneRose
class node_user,node_sunat toneIndigo
```

## Components

### API y acceso

- [Aplicación FastAPI](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/main.py): `apps/api/main.py`
- [Rutas RUC](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/router.py): `apps/api/app/api/ruc/router.py`
- [Autenticación](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/core/security.py): `apps/api/app/core/security.py`
- [Servicio RUC](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.py): `apps/api/app/api/ruc/service.py`
- [Caché TTL](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.py): `apps/api/app/api/ruc/service.py`
- [Exportación](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.py): `apps/api/app/api/ruc/service.py`
- [Estadísticas y estado](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/api/ruc/service.py): `apps/api/app/api/ruc/service.py`

### Interfaz web

- [Rutas web](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/api/app/web/routes.py): `apps/api/app/web/routes.py`
- [Plantillas UI](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/tree/main/apps/api/app/web): `apps/api/app/web`

### Actualizador padrón

- [CLI actualizador](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/main.py): `apps/updater/main.py`
- [Coordinador actualización](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/update_service.py): `apps/updater/services/update_service.py`
- [Descarga y cambios](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/download_service.py): `apps/updater/services/download_service.py`
- [Extracción TXT](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/extract_service.py): `apps/updater/services/extract_service.py`
- [Carga padrón](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/load_service.py): `apps/updater/services/load_service.py`
- [Parseo de líneas](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/parse_service.py): `apps/updater/services/parse_service.py`
- [Creación índices](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/index_service.py): `apps/updater/services/index_service.py`
- [Publicación atómica](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/apps/updater/services/publish_service.py): `apps/updater/services/publish_service.py`

### Servicios compartidos

- [Base contribuyentes](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/tree/main/data): `data`
- [Conexión SQLite](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/packages/database/connection.py): `packages/database/connection.py`
- [Metadatos actualización](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/tree/main/data): `data`
- [Detección codificación](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/packages/utils/encodings.py): `packages/utils/encodings.py`
- [Operaciones SQLite](https://github.com/barretopalacios/sistema-de-consulta-ruc-sunat/blob/main/packages/database/sqlite.py): `packages/database/sqlite.py`

### Other components

- **Usuario**
- **Fuente ZIP SUNAT**

## Connections

- Usuario → Aplicación FastAPI: solicita API
- Aplicación FastAPI → Rutas RUC: dirige rutas
- Rutas RUC → Autenticación: verifica token
- Rutas RUC → Servicio RUC: consulta y exporta
- Servicio RUC → Caché TTL: lee y escribe
- Servicio RUC → Conexión SQLite: abre conexión
- Conexión SQLite → Base contribuyentes: lee SQLite
- Usuario → Rutas web: busca en web
- Rutas web → Servicio RUC: consulta RUC
- Rutas web → Plantillas UI: renderiza páginas
- Rutas web → Metadatos actualización: lee estado
- Servicio RUC → Estadísticas y estado: calcula métricas
- Rutas RUC → Estadísticas y estado: solicita métricas
- Rutas RUC → Exportación: solicita exportación
- Usuario → CLI actualizador: ejecuta CLI
- CLI actualizador → Coordinador actualización: inicia actualización
- CLI actualizador → Descarga y cambios: comprueba cambios
- Coordinador actualización → Descarga y cambios: comprueba y descarga
- Descarga y cambios → Fuente ZIP SUNAT: consulta y descarga
- Descarga y cambios → Metadatos actualización: lee y guarda
- Coordinador actualización → Extracción TXT: extrae TXT
- Coordinador actualización → Carga padrón: carga registros
- Carga padrón → Parseo de líneas: parsea líneas
- Carga padrón → Detección codificación: detecta codificación
- Carga padrón → Operaciones SQLite: inserta lotes
- Coordinador actualización → Creación índices: crea índices
- Coordinador actualización → Publicación atómica: valida y publica
- Publicación atómica → Base contribuyentes: reemplaza base activa
- Rutas web → Servicio RUC: consulta estadísticas