# jlnetosci/ocarctic architecture

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

- Interactive diagram: https://gitdiagram.com/jlnetosci/ocarctic
- Repository: https://github.com/jlnetosci/ocarctic

## Overview

##### Project type and purpose
- This is a single-process, multi-page Streamlit web application (“OCaRctic”) for interactive image processing and transcription.
- The user uploads or selects example images, then steps through a pipeline: crop, preview, refine, view refined result, get transcription, and see usage tips.

##### File structure
- Top level
- streamlit_app.py – the Streamlit entrypoint that bootstraps the app and loads pages
- .streamlit/config.toml – Streamlit runtime configuration (theme, server settings)
- requirements.txt & packages.txt – Python and deployment dependencies
- pages/ – six submodules, each representing one page in the app UI (crop.py, preview.py, refine.py, refined.py, transcription.py, tips.py)
- No separate “backend” or database; all logic runs in the same process.

##### README for additional insights
- Minimal README: confirms it’s a hackathon entry for an open, AI-driven pipeline.
- No external database or microservice architecture is mentioned.

##### Main components
a. Client (Web Browser)
- Renders the Streamlit UI and handles user file uploads or selections.
b. Streamlit Server (streamlit_app.py + pages/)
- UI Layer: the six pages, each importing UI widgets and canvases.
- Business Logic Layer: image cropping, preview rendering, refinement algorithms, OCR/transcription.
c. Static Asset Store
- examples/ and img/ folders on local disk or container volume.
d. Dependency Layer
- Python environment (packages from requirements.txt).
- Possible external APIs or ML models (if the code calls an external AI inference service).

##### Relationships and data flows
- User → (HTTP) → Streamlit Server
- On each page:
1. File upload triggers image data passed into the cropping function.
2. Cropped output flows to the preview page.
3. Previewed image is forwarded to the refine algorithm.
4. Refined image is displayed on “refined” page.
5. Final image is sent to OCR/transcription logic on “transcription” page.
- Tips page reads static markdown or configuration to guide user.
- All pages can read/write to a temporary in-memory state or cache on disk.

##### Architectural patterns and design principles
- Monolithic, event-driven UI where each page is a module under Streamlit’s “pages” feature.
- Clear separation: UI layer (Streamlit widgets) vs. processing layer (image algorithms, OCR).
- Configuration externalized (.streamlit/config.toml, requirements.txt).
- Assets packaged alongside code (examples/, img/).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    User["User Browser"]:::client

    %% Entry Point
    Entry["Streamlit Entry: streamlit_app.py"]:::server
    click Entry "https://github.com/jlnetosci/ocarctic/blob/main/streamlit_app.py"

    %% UI Modules
    subgraph "UI Modules" 
        Crop["Crop Page: pages/crop.py"]:::ui
        click Crop "https://github.com/jlnetosci/ocarctic/blob/main/pages/crop.py"
        Preview["Preview Page: pages/preview.py"]:::ui
        click Preview "https://github.com/jlnetosci/ocarctic/blob/main/pages/preview.py"
        Refine["Refine Page: pages/refine.py"]:::ui
        click Refine "https://github.com/jlnetosci/ocarctic/blob/main/pages/refine.py"
        Refined["Refined Page: pages/refined.py"]:::ui
        click Refined "https://github.com/jlnetosci/ocarctic/blob/main/pages/refined.py"
        Transcribe["Transcription Page: pages/transcription.py"]:::ui
        click Transcribe "https://github.com/jlnetosci/ocarctic/blob/main/pages/transcription.py"
        Tips["Tips Page: pages/tips.py"]:::ui
        click Tips "https://github.com/jlnetosci/ocarctic/blob/main/pages/tips.py"
    end

    %% Asset Store
    ExAssets["Example Images\nexamples/"]:::storage
    click ExAssets "https://github.com/jlnetosci/ocarctic/tree/main/examples/"
    ImgAssets["Icons & Diagrams\nimg/"]:::storage
    click ImgAssets "https://github.com/jlnetosci/ocarctic/tree/main/img/"

    %% Config & Dependencies
    subgraph "Configuration & Dependencies"
        Config["Streamlit Config\n.streamlit/config.toml"]:::config
        click Config "https://github.com/jlnetosci/ocarctic/blob/main/.streamlit/config.toml"
        Requirements["requirements.txt"]:::dependency
        click Requirements "https://github.com/jlnetosci/ocarctic/blob/main/requirements.txt"
        Packages["packages.txt"]:::dependency
        click Packages "https://github.com/jlnetosci/ocarctic/blob/main/packages.txt"
    end

    %% Documentation & Meta
    subgraph "Project Docs & Meta"
        Readme["README.md"]:::doc
        click Readme "https://github.com/jlnetosci/ocarctic/blob/main/README.md"
        License["LICENSE"]:::doc
        click License "https://github.com/jlnetosci/ocarctic/tree/main/LICENSE"
        Gitignore[".gitignore"]:::doc
        click Gitignore "https://github.com/jlnetosci/ocarctic/blob/main/.gitignore"
    end

    %% Data Flow
    User -->|uploads/selects image| Entry
    Entry --> Crop
    Crop --> Preview
    Preview --> Refine
    Refine --> Refined
    Refined --> Transcribe
    Entry --> Tips

    %% Asset Access
    Crop --> ExAssets
    Crop --> ImgAssets
    Preview --> ImgAssets
    Refine --> ImgAssets
    Refined --> ImgAssets
    Transcribe --> ImgAssets
    Tips --> ImgAssets

    %% Config & Dependencies Usage
    Config --> Entry
    Requirements --> Entry
    Packages --> Entry

    %% Styles
    classDef client fill:#a0c4ff,stroke:#333,stroke-width:1px;
    classDef server fill:#bde0fe,stroke:#333,stroke-width:1px;
    classDef ui fill:#d8f3dc,stroke:#333,stroke-width:1px;
    classDef storage fill:#ffe066,stroke:#333,stroke-width:1px;
    classDef config fill:#ffc8dd,stroke:#333,stroke-width:1px;
    classDef dependency fill:#ffadad,stroke:#333,stroke-width:1px;
    classDef doc fill:#cdb4db,stroke:#333,stroke-width:1px;
```
