# urbanogilson/sicar architecture

> Architecture diagram of the GitHub repository urbanogilson/sicar, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/urbanogilson/sicar
- Repository: https://github.com/urbanogilson/sicar

## Overview

##### Project type and purpose
- Type: Open-source Python package (library + CLI/entry-points)
- Purpose: Automate the download of Brazilian land-registry (CAR) data, optionally solving CAPTCHAs via OCR drivers, and saving results as files.

##### Main components
A. Client / Entry Points
– Examples / CLI (examples/colab.ipynb, examples/docker.py)
– Docker Image & DevContainer
B. Core Library (package `SICAR/`)
1. Sicar (SICAR/sicar.py) – orchestrator, public API
2. State & Polygon (SICAR/state.py, SICAR/polygon.py) – enums for data scoping
3. URL Builder (SICAR/url.py) – constructs HTTP endpoints
4. Drivers (SICAR/drivers/*.py) – abstracted OCR interfaces:
- Tesseract driver
- PaddleOCR driver
5. Exceptions (SICAR/exceptions.py) – error handling
C. Data Layer
– File System I/O (writes downloaded ZIPs, polygons, states)
D. External Services
1. CAR Public Website REST endpoints
2. Google Tesseract OCR Engine (optional)
3. PaddleOCR Engine (optional)
4. Docker Hub (for container image)

##### Relationships & data flow
- The user invokes SICAR via Python code, notebook, or Docker.
- `Sicar` class calls `URL Builder` to generate request URLs.
- HTTP requests go to the CAR website.
- When a CAPTCHA is returned, `Sicar` delegates to the configured OCR `Driver` (Tesseract or Paddle).
- The chosen `Driver` calls into the external OCR engine, returns the recognized text.
- `Sicar` retries the HTTP request with CAPTCHA solution; once successful, it streams or downloads data.
- Downloaded files are written to the local file system.
- All components raise or catch custom exceptions where needed.

##### Architectural patterns & design principles
- Modular design: separation of concerns between orchestration (Sicar), URL generation, OCR drivers, and file I/O.
- Strategy pattern: interchangeable OCR drivers via a common interface.
- Single responsibility: each module focuses on one aspect (parsing, HTTP, OCR, FS).
- Dependency inversion for OCR: `Sicar` depends on abstract driver, not concrete implementations.

##### Essential elements
- Clear component names (e.g., “Sicar (core)”, “URL Builder”, “Tesseract Driver”).
- Annotations for protocols (HTTP, local FS, OCR engines).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client / Entry Points"
        COLAB["Colab Notebook"]:::client
        DOCKERPY["Docker Script"]:::client
        DOCKERFILE["Dockerfile"]:::client
        DEV_DOCKERFILE[".devcontainer Dockerfile"]:::client
        DEV_JSON[".devcontainer devcontainer.json"]:::client
    end

    subgraph "Core Library (Internal)"
        SC["Sicar (core)"]:::core
        URL["URL Builder"]:::core
        STATE["State Enum"]:::core
        POLY["Polygon Enum"]:::core
        EXC["Exceptions"]:::core
    end

    subgraph "OCR Drivers"
        IFACE["Driver Interface"]:::core
        TES["Tesseract Driver"]:::core
        PAD["PaddleOCR Driver"]:::core
    end

    FS["File System I/O"]:::io

    subgraph "External Systems"
        CAR["CAR Public Website"]:::external
        TESS_ENGINE["Tesseract OCR Engine"]:::external
        PAD_ENGINE["PaddleOCR Engine"]:::external
        DOCKERHUB["Docker Hub"]:::external
    end

    subgraph "Test Suite"
        UNIT["Unit Tests"]:::test
        INTEG["Integration Tests"]:::test
    end

    %% Relationships
    COLAB -->|"invokes"| SC
    DOCKERPY --> SC
    DOCKERFILE --> SC
    DEV_DOCKERFILE --> SC
    DEV_JSON --> SC
    DOCKERFILE -->|"push image"| DOCKERHUB

    SC -->|"builds URL"| URL
    URL -->|"HTTPS request"| CAR
    CAR -->|"returns CAPTCHA"| SC

    SC -->|"handles exceptions"| EXC

    SC -->|"calls OCR"| IFACE
    IFACE --> TES
    IFACE --> PAD

    TES -->|"send image"| TESS_ENGINE
    PAD -->|"send image"| PAD_ENGINE

    SC -->|"write ZIP/metadata"| FS

    UNIT -.-> SC
    INTEG -.-> SC

    %% Click Events
    click COLAB "https://github.com/urbanogilson/sicar/blob/main/examples/colab.ipynb"
    click DOCKERPY "https://github.com/urbanogilson/sicar/blob/main/examples/docker.py"
    click DOCKERFILE "https://github.com/urbanogilson/sicar/tree/main/Dockerfile"
    click DEV_DOCKERFILE "https://github.com/urbanogilson/sicar/tree/main/.devcontainer/Dockerfile"
    click DEV_JSON "https://github.com/urbanogilson/sicar/blob/main/.devcontainer/devcontainer.json"
    click SC "https://github.com/urbanogilson/sicar/blob/main/SICAR/sicar.py"
    click STATE "https://github.com/urbanogilson/sicar/blob/main/SICAR/state.py"
    click POLY "https://github.com/urbanogilson/sicar/blob/main/SICAR/polygon.py"
    click URL "https://github.com/urbanogilson/sicar/blob/main/SICAR/url.py"
    click IFACE "https://github.com/urbanogilson/sicar/blob/main/SICAR/drivers/captcha.py"
    click TES "https://github.com/urbanogilson/sicar/blob/main/SICAR/drivers/tesseract.py"
    click PAD "https://github.com/urbanogilson/sicar/blob/main/SICAR/drivers/paddle.py"
    click EXC "https://github.com/urbanogilson/sicar/blob/main/SICAR/exceptions.py"
    click FS "https://github.com/urbanogilson/sicar/blob/main/SICAR/sicar.py"
    click UNIT "https://github.com/urbanogilson/sicar/tree/main/SICAR/tests/unit/"
    click INTEG "https://github.com/urbanogilson/sicar/tree/main/SICAR/tests/integration/"

    %% Styles
    classDef client fill:#E0F7FA,stroke:#006064,color:#006064
    classDef core fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1
    classDef external fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef io fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef test fill:#F3E5F5,stroke:#4A148C,color:#4A148C
```
