# wrishavsett/hsl architecture

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

- Interactive diagram: https://gitdiagram.com/wrishavsett/hsl
- Repository: https://github.com/wrishavsett/hsl

## Overview

HSL is a config-driven FastAPI invoice extraction service. A client uploads a PDF to `/extract`; the API validates and temporarily saves it, then the Gemini client loads extraction settings, rasterizes the PDF, and requests schema-constrained structured output from Gemini. The API resolves configured fields and returns JSON, while temporary files are cleaned up. The graph also retains the health check, shared error handling, and logging layer. Relationships follow the README and shown excerpts; unsampled implementation details are omitted.

Main entry points: [`src/api.py`](https://github.com/wrishavsett/hsl/blob/main/src/api.py) (FastAPI routes), [`src/gemini_client.py`](https://github.com/wrishavsett/hsl/blob/main/src/gemini_client.py) (Extraction orchestrator), [`src/helper.py`](https://github.com/wrishavsett/hsl/blob/main/src/helper.py) (Config validation), [`src/logger.py`](https://github.com/wrishavsett/hsl/blob/main/src/logger.py) (Logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["HTTP ingress"]
  node_api["FastAPI routes<br/>[api.py]"]
  node_upload["Upload validation<br/>[api.py]"]
  node_pdf_temp["Temporary PDF<br/>[api.py]"]
  node_field_resolver["Field resolver<br/>[helper.py]"]
  node_json_result["JSON response<br/>[api.py]"]
end

subgraph group_extraction["Extraction workflow"]
  node_extractor["Extraction orchestrator<br/>[gemini_client.py]"]
  node_config_loader["Config validation<br/>[helper.py]"]
  node_extraction_config["Extraction settings<br/>[extraction.json]"]
  node_pdf_rasterizer["PDF rasterization<br/>[helper.py]"]
  node_page_images["Rasterized pages<br/>[helper.py]"]
  node_gemini_client["Gemini client<br/>[gemini_client.py]"]
end

subgraph group_support["Shared services"]
  node_error_handling["Domain errors<br/>[error.py]"]
  node_logging["Logging<br/>[logger.py]"]
end

subgraph group_external["External dependencies"]
  node_pdf_tools["PDF tools"]
  node_gemini_service["Google Gemini"]
end

node_caller(("API caller"))

node_caller -->|"sends request"| node_api
node_api -->|"routes upload"| node_upload
node_upload -->|"saves PDF"| node_pdf_temp
node_api -->|"calls extraction"| node_extractor
node_extractor -->|"loads settings"| node_config_loader
node_config_loader -->|"reads config"| node_extraction_config
node_extractor -->|"rasterizes PDF"| node_pdf_rasterizer
node_pdf_rasterizer -->|"uses Poppler"| node_pdf_tools
node_pdf_rasterizer -->|"writes images"| node_page_images
node_extractor -->|"calls model"| node_gemini_client
node_gemini_client -->|"reads images"| node_page_images
node_gemini_client -->|"sends prompt"| node_gemini_service
node_extractor -->|"cleans up"| node_page_images
node_api -->|"resolves fields"| node_field_resolver
node_api -->|"loads field map"| node_extraction_config
node_field_resolver -->|"produces data"| node_json_result
node_api -->|"returns JSON"| node_json_result
node_api -->|"catches errors"| node_error_handling
node_api -->|"logs events"| node_logging
node_extractor -->|"logs events"| node_logging
node_config_loader -->|"logs issues"| node_logging

click node_api "https://github.com/wrishavsett/hsl/blob/main/src/api.py"
click node_upload "https://github.com/wrishavsett/hsl/blob/main/src/api.py"
click node_pdf_temp "https://github.com/wrishavsett/hsl/blob/main/src/api.py"
click node_field_resolver "https://github.com/wrishavsett/hsl/blob/main/src/helper.py"
click node_json_result "https://github.com/wrishavsett/hsl/blob/main/src/api.py"
click node_extractor "https://github.com/wrishavsett/hsl/blob/main/src/gemini_client.py"
click node_config_loader "https://github.com/wrishavsett/hsl/blob/main/src/helper.py"
click node_extraction_config "https://github.com/wrishavsett/hsl/blob/main/configs/extraction.json"
click node_pdf_rasterizer "https://github.com/wrishavsett/hsl/blob/main/src/helper.py"
click node_page_images "https://github.com/wrishavsett/hsl/blob/main/src/helper.py"
click node_gemini_client "https://github.com/wrishavsett/hsl/blob/main/src/gemini_client.py"
click node_error_handling "https://github.com/wrishavsett/hsl/blob/main/src/error.py"
click node_logging "https://github.com/wrishavsett/hsl/blob/main/src/logger.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,node_upload,node_pdf_temp,node_field_resolver,node_json_result toneBlue
class node_extractor,node_config_loader,node_extraction_config,node_pdf_rasterizer,node_page_images,node_gemini_client toneAmber
class node_error_handling,node_logging,node_caller toneMint
class node_pdf_tools,node_gemini_service toneRose
```

## Components

### HTTP ingress

- [FastAPI routes](https://github.com/wrishavsett/hsl/blob/main/src/api.py): `src/api.py`
- [Upload validation](https://github.com/wrishavsett/hsl/blob/main/src/api.py): `src/api.py`
- [Temporary PDF](https://github.com/wrishavsett/hsl/blob/main/src/api.py): `src/api.py`
- [Field resolver](https://github.com/wrishavsett/hsl/blob/main/src/helper.py): `src/helper.py`
- [JSON response](https://github.com/wrishavsett/hsl/blob/main/src/api.py): `src/api.py`

### Extraction workflow

- [Extraction orchestrator](https://github.com/wrishavsett/hsl/blob/main/src/gemini_client.py): `src/gemini_client.py`
- [Config validation](https://github.com/wrishavsett/hsl/blob/main/src/helper.py): `src/helper.py`
- [Extraction settings](https://github.com/wrishavsett/hsl/blob/main/configs/extraction.json): `configs/extraction.json`
- [PDF rasterization](https://github.com/wrishavsett/hsl/blob/main/src/helper.py): `src/helper.py`
- [Rasterized pages](https://github.com/wrishavsett/hsl/blob/main/src/helper.py): `src/helper.py`
- [Gemini client](https://github.com/wrishavsett/hsl/blob/main/src/gemini_client.py): `src/gemini_client.py`

### Shared services

- [Domain errors](https://github.com/wrishavsett/hsl/blob/main/src/error.py): `src/error.py`
- [Logging](https://github.com/wrishavsett/hsl/blob/main/src/logger.py): `src/logger.py`

### External dependencies

- **PDF tools**
- **Google Gemini**

### Other components

- **API caller**

## Connections

- API caller → FastAPI routes: sends request (evidence: `README.md`)
- FastAPI routes → Upload validation: routes upload (evidence: `src/api.py`)
- Upload validation → Temporary PDF: saves PDF (evidence: `src/api.py`)
- FastAPI routes → Extraction orchestrator: calls extraction (evidence: `src/api.py`)
- Extraction orchestrator → Config validation: loads settings (evidence: `src/gemini_client.py`)
- Config validation → Extraction settings: reads config (evidence: `README.md`)
- Extraction orchestrator → PDF rasterization: rasterizes PDF (evidence: `src/gemini_client.py`)
- PDF rasterization → PDF tools: uses Poppler (evidence: `README.md`)
- PDF rasterization → Rasterized pages: writes images (evidence: `README.md`)
- Extraction orchestrator → Gemini client: calls model (evidence: `src/gemini_client.py`)
- Gemini client → Rasterized pages: reads images (evidence: `src/gemini_client.py`)
- Gemini client → Google Gemini: sends prompt (evidence: `src/gemini_client.py`)
- Extraction orchestrator → Rasterized pages: cleans up (evidence: `src/gemini_client.py`)
- FastAPI routes → Field resolver: resolves fields (evidence: `src/api.py`)
- FastAPI routes → Extraction settings: loads field map (evidence: `src/api.py`)
- Field resolver → JSON response: produces data (evidence: `src/api.py`)
- FastAPI routes → JSON response: returns JSON (evidence: `src/api.py`)
- FastAPI routes → Domain errors: catches errors (evidence: `src/api.py`)
- FastAPI routes → Logging: logs events (evidence: `src/api.py`)
- Extraction orchestrator → Logging: logs events (evidence: `src/gemini_client.py`)
- Config validation → Logging: logs issues (evidence: `src/helper.py`)
