# bestroi150/lumina architecture

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

- Interactive diagram: https://gitdiagram.com/bestroi150/lumina
- Repository: https://github.com/bestroi150/lumina

## Overview

Lumina is a Streamlit application for turning manuscript page images into editable transcriptions, text-mining results, geographic entities, geolocations, and downloadable outputs. Users move through five documented stages; the app also accepts text-file overrides and custom recognition models. Most stage logic resides in app.py, with Kraken operations and baseline visualization delegated to library modules. The source excerpts are partial, so stage links rely on the README’s documented workflow; detailed internal calls for unsampled stages are not inferred.

Main entry points: [`app.py`](https://github.com/bestroi150/lumina/blob/main/app.py) (Transcription), [`lib/kraken_utils.py`](https://github.com/bestroi150/lumina/blob/main/lib/kraken_utils.py) (Baseline segmentation), [`data/default/blla.mlmodel`](https://github.com/bestroi150/lumina/blob/main/data/default/blla.mlmodel) (BLLA model), [`models`](https://github.com/bestroi150/lumina/tree/main/models) (HTR models)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["User workflow"]
  node_export["Results export<br/>[app.py]"]
end

subgraph group_ocr["OCR and models"]
  node_transcription["Transcription<br/>[app.py]"]
  node_segmentation["Baseline segmentation<br/>[kraken_utils.py]"]
  node_recognition["Text recognition<br/>[kraken_utils.py]"]
  node_segment_model["BLLA model<br/>[blla.mlmodel]"]
  node_recognition_models["HTR models"]
  node_baseline_display["Baseline visualization<br/>[display_utils.py]"]
  node_model_config["Model metadata<br/>[constants.py]"]
end

subgraph group_analysis["Text analysis"]
  node_mining["Data mining<br/>[app.py]"]
  node_text_override["Text-file override<br/>[app.py]"]
  node_ner["Named entity recognition<br/>[app.py]"]
  node_spacy["French spaCy model"]
end

subgraph group_geography["Geolocation"]
  node_geolocation["Geolocation<br/>[app.py]"]
  node_groq["Groq API"]
  node_map_history["Map and history<br/>[app.py]"]
end

subgraph group_presentation["App and visualization"]
  node_app["Streamlit workflow<br/>[app.py]"]
end

node_user(("Document analyst"))

node_user -->|"uses"| node_app
node_app -->|"renders"| node_transcription
node_transcription -->|"segments images"| node_segmentation
node_segmentation -.->|"loads model"| node_segment_model
node_transcription -->|"recognizes text"| node_recognition
node_recognition -->|"uses selected model"| node_recognition_models
node_transcription -->|"shows overlays"| node_baseline_display
node_app -.->|"uses metadata"| node_model_config
node_transcription -->|"provides text"| node_mining
node_user -->|"uploads text"| node_text_override
node_text_override -->|"overrides input"| node_mining
node_mining -->|"feeds text"| node_ner
node_ner -->|"extracts entities"| node_spacy
node_ner -->|"forwards places"| node_geolocation
node_geolocation -->|"requests coordinates"| node_groq
node_geolocation -->|"records results"| node_map_history
node_app -->|"offers downloads"| node_export

click node_app "https://github.com/bestroi150/lumina/blob/main/app.py"
click node_transcription "https://github.com/bestroi150/lumina/blob/main/app.py"
click node_segmentation "https://github.com/bestroi150/lumina/blob/main/lib/kraken_utils.py"
click node_recognition "https://github.com/bestroi150/lumina/blob/main/lib/kraken_utils.py"
click node_segment_model "https://github.com/bestroi150/lumina/blob/main/data/default/blla.mlmodel"
click node_recognition_models "https://github.com/bestroi150/lumina/tree/main/models"
click node_baseline_display "https://github.com/bestroi150/lumina/blob/main/lib/display_utils.py"
click node_mining "https://github.com/bestroi150/lumina/blob/main/app.py"
click node_text_override "https://github.com/bestroi150/lumina/blob/main/app.py"
click node_ner "https://github.com/bestroi150/lumina/blob/main/app.py"
click node_geolocation "https://github.com/bestroi150/lumina/blob/main/app.py"
click node_map_history "https://github.com/bestroi150/lumina/blob/main/app.py"
click node_export "https://github.com/bestroi150/lumina/blob/main/app.py"
click node_model_config "https://github.com/bestroi150/lumina/blob/main/lib/constants.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_export toneBlue
class node_transcription,node_segmentation,node_recognition,node_segment_model,node_recognition_models,node_baseline_display,node_model_config toneAmber
class node_mining,node_text_override,node_ner,node_spacy toneMint
class node_geolocation,node_groq,node_map_history toneRose
class node_app,node_user toneIndigo
```

## Components

### User workflow

- [Results export](https://github.com/bestroi150/lumina/blob/main/app.py): `app.py`

### OCR and models

- [Transcription](https://github.com/bestroi150/lumina/blob/main/app.py): `app.py`
- [Baseline segmentation](https://github.com/bestroi150/lumina/blob/main/lib/kraken_utils.py): `lib/kraken_utils.py`
- [Text recognition](https://github.com/bestroi150/lumina/blob/main/lib/kraken_utils.py): `lib/kraken_utils.py`
- [BLLA model](https://github.com/bestroi150/lumina/blob/main/data/default/blla.mlmodel): `data/default/blla.mlmodel`
- [HTR models](https://github.com/bestroi150/lumina/tree/main/models): `models`
- [Baseline visualization](https://github.com/bestroi150/lumina/blob/main/lib/display_utils.py): `lib/display_utils.py`
- [Model metadata](https://github.com/bestroi150/lumina/blob/main/lib/constants.py): `lib/constants.py`

### Text analysis

- [Data mining](https://github.com/bestroi150/lumina/blob/main/app.py): `app.py`
- [Text-file override](https://github.com/bestroi150/lumina/blob/main/app.py): `app.py`
- [Named entity recognition](https://github.com/bestroi150/lumina/blob/main/app.py): `app.py`
- **French spaCy model**

### Geolocation

- [Geolocation](https://github.com/bestroi150/lumina/blob/main/app.py): `app.py`
- **Groq API**
- [Map and history](https://github.com/bestroi150/lumina/blob/main/app.py): `app.py`

### App and visualization

- [Streamlit workflow](https://github.com/bestroi150/lumina/blob/main/app.py): `app.py`

### Other components

- **Document analyst**

## Connections

- Document analyst → Streamlit workflow: uses (evidence: `README.md`)
- Streamlit workflow → Transcription: renders (evidence: `README.md`)
- Transcription → Baseline segmentation: segments images (evidence: `app.py`)
- Baseline segmentation → BLLA model: loads model
- Transcription → Text recognition: recognizes text (evidence: `app.py`)
- Text recognition → HTR models: uses selected model (evidence: `README.md`)
- Transcription → Baseline visualization: shows overlays (evidence: `README.md`)
- Streamlit workflow → Model metadata: uses metadata
- Transcription → Data mining: provides text (evidence: `README.md`)
- Document analyst → Text-file override: uploads text (evidence: `README.md`)
- Text-file override → Data mining: overrides input (evidence: `README.md`)
- Data mining → Named entity recognition: feeds text (evidence: `README.md`)
- Named entity recognition → French spaCy model: extracts entities (evidence: `README.md`)
- Named entity recognition → Geolocation: forwards places (evidence: `README.md`)
- Geolocation → Groq API: requests coordinates (evidence: `app.py`)
- Geolocation → Map and history: records results (evidence: `README.md`)
- Streamlit workflow → Results export: offers downloads (evidence: `README.md`)