# dccaceres/ruc-dnit architecture

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

- Interactive diagram: https://gitdiagram.com/dccaceres/ruc-dnit
- Repository: https://github.com/dccaceres/ruc-dnit

## Overview

DNIT RUC Zip Downloader combines a CLI-driven data-ingestion workflow with a REST API for RUC lookup. The documented ingestion stages are page link discovery, ZIP download and extraction, TXT unification, CSV validation, and SQLite creation; API requests then query that database and format results. The README documents the complete ingestion capabilities, while the excerpts show the CLI-to-downloader call and API query implementation. Some ingestion-stage connections are therefore documented rather than independently visible in the sampled code.

Main entry points: [`src/api.py`](https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py) (REST API), [`src/downloader.py`](https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py) (CSV validation), [`src/main.py`](https://github.com/dccaceres/ruc-dnit/blob/master/src/main.py) (Downloader CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Data ingestion"]
  node_cli["Downloader CLI<br/>[main.py]"]
  node_zip_discovery["ZIP discovery<br/>[downloader.py]"]
  node_zip_download["ZIP download<br/>[downloader.py]"]
  node_zip_extract["ZIP extraction<br/>[downloader.py]"]
end

subgraph group_processing["Data processing"]
  node_txt_unify["TXT unification<br/>[downloader.py]"]
  node_csv_validation["CSV validation<br/>[downloader.py]"]
  node_sqlite_creation["SQLite creation<br/>[downloader.py]"]
end

subgraph group_api["RUC API"]
  node_api_server["REST API<br/>[api.py]"]
  node_exact_lookup["Exact RUC lookup<br/>[api.py]"]
  node_text_search["Name search<br/>[api.py]"]
  node_response_format["Response formatting<br/>[api.py]"]
  node_health_status["Health check<br/>[api.py]"]
end

subgraph group_storage["RUC storage"]
  node_csv_file["Validated CSV<br/>[downloader.py]"]
  node_database[("RUC database")]
end

node_operator(("Operator"))
node_source_site["DNIT website"]

node_operator -->|"runs"| node_cli
node_cli -->|"processes URL"| node_zip_discovery
node_source_site -->|"provides page"| node_zip_discovery
node_zip_discovery -.->|"finds links"| node_zip_download
node_zip_download -.->|"downloads archives"| node_zip_extract
node_zip_extract -.->|"supplies TXT files"| node_txt_unify
node_txt_unify -->|"writes CSV"| node_csv_validation
node_csv_validation -->|"cleans data"| node_csv_file
node_csv_validation -->|"validates input"| node_sqlite_creation
node_sqlite_creation -->|"writes records"| node_database
node_operator -->|"queries"| node_api_server
node_api_server -->|"routes exact lookup"| node_exact_lookup
node_api_server -->|"routes search"| node_text_search
node_exact_lookup -->|"queries RUC"| node_database
node_text_search -->|"queries names"| node_database
node_api_server -->|"serves health"| node_health_status
node_exact_lookup -->|"formats match"| node_response_format
node_text_search -->|"formats results"| node_response_format

click node_cli "https://github.com/dccaceres/ruc-dnit/blob/master/src/main.py"
click node_zip_discovery "https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py"
click node_zip_download "https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py"
click node_zip_extract "https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py"
click node_txt_unify "https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py"
click node_csv_validation "https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py"
click node_sqlite_creation "https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py"
click node_csv_file "https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py"
click node_api_server "https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py"
click node_exact_lookup "https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py"
click node_text_search "https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py"
click node_response_format "https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py"
click node_health_status "https://github.com/dccaceres/ruc-dnit/blob/master/src/api.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_cli,node_zip_discovery,node_zip_download,node_zip_extract toneBlue
class node_txt_unify,node_csv_validation,node_sqlite_creation toneAmber
class node_api_server,node_exact_lookup,node_text_search,node_response_format,node_health_status toneMint
class node_csv_file,node_database toneRose
class node_operator,node_source_site toneIndigo
```

## Components

### Data ingestion

- [Downloader CLI](https://github.com/dccaceres/ruc-dnit/blob/master/src/main.py): `src/main.py`
- [ZIP discovery](https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py): `src/downloader.py`
- [ZIP download](https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py): `src/downloader.py`
- [ZIP extraction](https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py): `src/downloader.py`

### Data processing

- [TXT unification](https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py): `src/downloader.py`
- [CSV validation](https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py): `src/downloader.py`
- [SQLite creation](https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py): `src/downloader.py`

### RUC API

- [REST API](https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py): `src/api.py`
- [Exact RUC lookup](https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py): `src/api.py`
- [Name search](https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py): `src/api.py`
- [Response formatting](https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py): `src/api.py`
- [Health check](https://github.com/dccaceres/ruc-dnit/blob/master/src/api.py): `src/api.py`

### RUC storage

- [Validated CSV](https://github.com/dccaceres/ruc-dnit/blob/master/src/downloader.py): `src/downloader.py`
- **RUC database**

### Other components

- **Operator**
- **DNIT website**

## Connections

- Operator → Downloader CLI: runs (evidence: `README.md`)
- Downloader CLI → ZIP discovery: processes URL (evidence: `src/main.py`)
- DNIT website → ZIP discovery: provides page (evidence: `README.md`)
- ZIP discovery → ZIP download: finds links (evidence: `src/downloader.py`)
- ZIP download → ZIP extraction: downloads archives (evidence: `src/downloader.py`)
- ZIP extraction → TXT unification: supplies TXT files (evidence: `src/downloader.py`)
- TXT unification → CSV validation: writes CSV (evidence: `src/downloader.py`)
- CSV validation → Validated CSV: cleans data (evidence: `README.md`)
- CSV validation → SQLite creation: validates input (evidence: `src/downloader.py`)
- SQLite creation → RUC database: writes records (evidence: `src/downloader.py`)
- Operator → REST API: queries (evidence: `README.md`)
- REST API → Exact RUC lookup: routes exact lookup (evidence: `src/api.py`)
- REST API → Name search: routes search (evidence: `src/api.py`)
- Exact RUC lookup → RUC database: queries RUC (evidence: `src/api.py`)
- Name search → RUC database: queries names (evidence: `src/api.py`)
- REST API → Health check: serves health (evidence: `src/api.py`)
- Exact RUC lookup → Response formatting: formats match (evidence: `src/api.py`)
- Name search → Response formatting: formats results (evidence: `src/api.py`)
