# josespx/apiconsultasunatruc architecture

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

## Overview

Consulta RUC Sunat is a Flask API that retrieves taxpayer details from SUNAT in real time. The main workflow validates a submitted RUC, obtains SUNAT’s CAPTCHA image and cookies, OCRs the image, uses the recognized text to request taxpayer data, parses the returned HTML, and serializes the result as JSON. The API also exposes a simple health response. The graph follows the sampled route and helper calls; the README documents scraping and OCR, while wiring beyond those excerpts is omitted.

Main entry points: [`app/routes/sunat.py`](https://github.com/josespx/apiconsultasunatruc/blob/master/app/routes/sunat.py) (RUC Endpoint), [`app/helpers/tesseract.py`](https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/tesseract.py) (Image OCR), [`app/helpers/sunatinfo.py`](https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/sunatinfo.py) (Field Parser), [`app/__init__.py`](https://github.com/josespx/apiconsultasunatruc/blob/master/app/__init__.py) (Flask App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API"]
  node_flask["Flask App<br/>[__init__.py]"]
  node_sunat_route["RUC Endpoint<br/>[sunat.py]"]
  node_home_route["Health Endpoint<br/>[home.py]"]
end

subgraph group_captcha["CAPTCHA OCR"]
  node_captcha_reader["Image OCR<br/>[tesseract.py]"]
  node_ocr_engine["Tesseract OCR"]
end

subgraph group_lookup["SUNAT Lookup"]
  node_info_reader["HTML Retrieval<br/>[sunatinfo.py]"]
  node_field_parser["Field Parser<br/>[sunatinfo.py]"]
  node_layout_constants["Layout Constants<br/>[sunatconstants.py]"]
  node_info_model["Taxpayer Model<br/>[sunatinfo.py]"]
end

subgraph group_setup["Runtime Configuration"]
  node_config["SUNAT Settings<br/>[config.py]"]
end

node_client(("API Client"))
node_sunat["SUNAT Service"]

node_client -->|"submits RUC"| node_sunat_route
node_sunat_route -->|"returns JSON"| node_client
node_client -->|"checks status"| node_home_route
node_home_route -->|"returns status"| node_client
node_flask -->|"registers route"| node_sunat_route
node_flask -->|"registers route"| node_home_route
node_config -->|"configures"| node_flask
node_sunat_route -->|"requests CAPTCHA text"| node_captcha_reader
node_captcha_reader -->|"fetches CAPTCHA"| node_sunat
node_captcha_reader -->|"recognizes text"| node_ocr_engine
node_sunat_route -->|"requests taxpayer data"| node_info_reader
node_info_reader -->|"fetches HTML"| node_sunat
node_sunat_route -->|"parses rows"| node_field_parser
node_field_parser -->|"reads field indices"| node_layout_constants
node_field_parser -->|"populates model"| node_info_model
node_sunat_route -->|"serializes response"| node_info_model

click node_flask "https://github.com/josespx/apiconsultasunatruc/blob/master/app/__init__.py"
click node_sunat_route "https://github.com/josespx/apiconsultasunatruc/blob/master/app/routes/sunat.py"
click node_home_route "https://github.com/josespx/apiconsultasunatruc/blob/master/app/routes/home.py"
click node_captcha_reader "https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/tesseract.py"
click node_info_reader "https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/sunatinfo.py"
click node_field_parser "https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/sunatinfo.py"
click node_layout_constants "https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/sunatconstants.py"
click node_info_model "https://github.com/josespx/apiconsultasunatruc/blob/master/app/models/sunatinfo.py"
click node_config "https://github.com/josespx/apiconsultasunatruc/blob/master/config.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_flask,node_sunat_route,node_home_route,node_client toneBlue
class node_captcha_reader,node_ocr_engine toneAmber
class node_info_reader,node_field_parser,node_layout_constants,node_info_model toneMint
class node_config toneRose
class node_sunat toneIndigo
```

## Components

### API

- [Flask App](https://github.com/josespx/apiconsultasunatruc/blob/master/app/__init__.py): `app/__init__.py`
- [RUC Endpoint](https://github.com/josespx/apiconsultasunatruc/blob/master/app/routes/sunat.py): `app/routes/sunat.py`
- [Health Endpoint](https://github.com/josespx/apiconsultasunatruc/blob/master/app/routes/home.py): `app/routes/home.py`

### CAPTCHA OCR

- [Image OCR](https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/tesseract.py): `app/helpers/tesseract.py`
- **Tesseract OCR**

### SUNAT Lookup

- [HTML Retrieval](https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/sunatinfo.py): `app/helpers/sunatinfo.py`
- [Field Parser](https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/sunatinfo.py): `app/helpers/sunatinfo.py`
- [Layout Constants](https://github.com/josespx/apiconsultasunatruc/blob/master/app/helpers/sunatconstants.py): `app/helpers/sunatconstants.py`
- [Taxpayer Model](https://github.com/josespx/apiconsultasunatruc/blob/master/app/models/sunatinfo.py): `app/models/sunatinfo.py`

### Runtime Configuration

- [SUNAT Settings](https://github.com/josespx/apiconsultasunatruc/blob/master/config.py): `config.py`

### Other components

- **API Client**
- **SUNAT Service**

## Connections

- API Client → RUC Endpoint: submits RUC
- RUC Endpoint → API Client: returns JSON
- API Client → Health Endpoint: checks status
- Health Endpoint → API Client: returns status
- Flask App → RUC Endpoint: registers route
- Flask App → Health Endpoint: registers route
- SUNAT Settings → Flask App: configures
- RUC Endpoint → Image OCR: requests CAPTCHA text
- Image OCR → SUNAT Service: fetches CAPTCHA
- Image OCR → Tesseract OCR: recognizes text
- RUC Endpoint → HTML Retrieval: requests taxpayer data
- HTML Retrieval → SUNAT Service: fetches HTML
- RUC Endpoint → Field Parser: parses rows
- Field Parser → Layout Constants: reads field indices
- Field Parser → Taxpayer Model: populates model
- RUC Endpoint → Taxpayer Model: serializes response