# petr-ngn/deepnote-hackathon architecture

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

- Interactive diagram: https://gitdiagram.com/petr-ngn/deepnote-hackathon
- Repository: https://github.com/petr-ngn/deepnote-hackathon

## Overview

##### Project type and purpose
- This is a full-stack Python application (a single-page Streamlit UI front-end plus a backend orchestrator) whose purpose is to extract financial data from scanned Czech company PDFs, enrich it with web-scraped company info, run LLM-powered financial analysis, and present results in an interactive dashboard.
- Key features: AWS Textract OCR processing, LLM integration via Amazon Bedrock and Anthropic Claude, web scraping with the Tavily API, AWS S3 storage, and a Streamlit-based UI.

##### File structure
- Top level:
- app.py — entrypoint which initializes Streamlit UI and kicks off processing
- Dockerfile, .dockerignore, pyproject.toml — project build & packaging
- config/ — YAML configs for LLM, OCR, scraper, UI
- src/ — core modules: aws.py, ocr.py, llm.py, scraper.py, ui.py, utils.py
- .github/workflows/pylint.yml — CI linting
- .pdf_examples/ — sample PDFs for demo
- Patterns:
- “src” implements a modular service-oriented architecture: each Python module encapsulates one external integration
- app.py and src/ui.py provide the UI layer; src/* share helper functions in utils.py
- config YAMLs parameterize external services, allowing easy swap or reconfiguration

##### Extract insights from README
- External services: AWS Textract, S3, Amazon Bedrock LLMs, Anthropic Claude, Tavily search API.
- Streamlit front-end drives file upload, displays progress spinners, and shows summary tables.

##### Essential architectural elements
- Service endpoint, data flow, and the orchestration sequence.
- Configuration injection (which drives credentials, adapter IDs, UI settings).
- Docker/Deepnote deployment boundary around the app & config files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        User["User"]:::frontend
        App["Streamlit App\n(app.py)"]:::frontend
        UI["UI Logic\n(src/ui.py)"]:::frontend
        ConfigUI["UI Config\n(config/ui.yaml)"]:::config
    end

    %% Backend Layer
    subgraph "Backend Layer"
        direction TB
        Orchestrator["Orchestrator\n(src/utils.py)"]:::backend
        OCRService["OCR Service\n(src/aws.py)"]:::backend
        ScraperService["Web Scraper\n(src/scraper.py)"]:::backend
        LLMService["LLM Integration\n(src/llm.py)"]:::backend
        S3["AWS S3\n(Storage)"]:::storage
        ConfigOCR["OCR Config\n(config/ocr.yaml)"]:::config
        ConfigScraper["Scraper Config\n(config/scraper.yaml)"]:::config
        ConfigLLM["LLM Config\n(config/llm.yaml)"]:::config
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        AWS_Textract["AWS Textract"]:::external
        Tavily["Tavily API"]:::external
        Bedrock_Claude["Bedrock & Claude LLMs"]:::external
    end

    %% Deployment & CI
    subgraph "Deployment / CI"
        direction TB
        Dockerfile["Dockerfile"]:::deploy
        Dockerignore[".dockerignore"]:::deploy
        CI["CI Lint\n(.github/workflows/pylint.yml)"]:::ci
    end

    %% Data Flows
    User -->|Upload PDF| UI
    UI -->|Invoke pipeline| Orchestrator
    ConfigUI --> UI

    Orchestrator -->|Call OCR| OCRService
    ConfigOCR --> OCRService
    OCRService -->|Invoke Textract| AWS_Textract
    AWS_Textract -->|Return tables| OCRService
    OCRService -->|Store output| S3

    Orchestrator -->|Call Scraper| ScraperService
    ConfigScraper --> ScraperService
    ScraperService -->|Search| Tavily
    Tavily -->|Return web data| ScraperService

    Orchestrator -->|Call LLM| LLMService
    ConfigLLM --> LLMService
    LLMService -->|Analyze| Bedrock_Claude
    Bedrock_Claude -->|Return analysis| LLMService
    LLMService -->|Store analysis| S3

    Orchestrator -->|Stream results| UI

    %% Deployment arrows
    Dockerfile --> App
    Dockerfile --> Orchestrator
    Dockerignore --> App
    Dockerignore --> Orchestrator

    CI --> App
    CI --> Orchestrator

    %% Click Events
    click App "https://github.com/petr-ngn/deepnote-hackathon/blob/main/app.py"
    click UI "https://github.com/petr-ngn/deepnote-hackathon/blob/main/src/ui.py"
    click ConfigUI "https://github.com/petr-ngn/deepnote-hackathon/blob/main/config/ui.yaml"
    click Orchestrator "https://github.com/petr-ngn/deepnote-hackathon/blob/main/src/utils.py"
    click OCRService "https://github.com/petr-ngn/deepnote-hackathon/blob/main/src/aws.py"
    click ConfigOCR "https://github.com/petr-ngn/deepnote-hackathon/blob/main/config/ocr.yaml"
    click ScraperService "https://github.com/petr-ngn/deepnote-hackathon/blob/main/src/scraper.py"
    click ConfigScraper "https://github.com/petr-ngn/deepnote-hackathon/blob/main/config/scraper.yaml"
    click LLMService "https://github.com/petr-ngn/deepnote-hackathon/blob/main/src/llm.py"
    click ConfigLLM "https://github.com/petr-ngn/deepnote-hackathon/blob/main/config/llm.yaml"
    click Dockerfile "https://github.com/petr-ngn/deepnote-hackathon/tree/main/Dockerfile"
    click Dockerignore "https://github.com/petr-ngn/deepnote-hackathon/blob/main/.dockerignore"
    click CI "https://github.com/petr-ngn/deepnote-hackathon/blob/main/.github/workflows/pylint.yml"

    %% Styles
    classDef frontend fill:#DCEEFB,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#E6FFFA,stroke:#038C73,color:#038C73;
    classDef external fill:#FFF4E6,stroke:#F59E0B,color:#F59E0B;
    classDef storage fill:#F3F4F6,stroke:#6B7280,color:#6B7280;
    classDef config fill:#EDE9FE,stroke:#7C3AED,color:#7C3AED;
    classDef deploy fill:#FDF2F8,stroke:#DB2777,color:#DB2777;
    classDef ci fill:#FEE2E2,stroke:#B91C1C,color:#B91C1C;
```
