# noeberdoz/julius_baer_onboarding architecture

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

- Interactive diagram: https://gitdiagram.com/noeberdoz/julius_baer_onboarding
- Repository: https://github.com/noeberdoz/julius_baer_onboarding

## Overview

##### Project Type and Purpose
- This is a full-stack web application combining a Python/Flask backend with a JavaScript/Alpine.js & Bootstrap frontend.
- It’s an AI-powered dossier review system: it ingests client documents (passport, account details, profile, description), applies OCR and LLM reasoning to extract and cross-validate data, and presents recommendations to end users in a gamified flow.

##### Top-Level Components
a. Frontend (frontend/)
- Technologies: Alpine.js, Bootstrap, Vite, Mammoth.js (for DOCX previews).
- Responsibilities: Display documents; show AI recommendations; collect user Accept/Reject decisions; manage game state.
b. Backend API (app.py, config.py)
- Framework: Flask.
- Exposes REST endpoints (e.g., /new-game, /next).
- Routes orchestrate request handling and delegate to service layer.
c. Services (services/)
- advisor.py: Central orchestration service that invokes extraction, validation, and LLM recommendation.
- extractor.py: Document processing for OCR/parsing per file type.
- julius_baer_api_client.py: Client to external hackathon API (game simulation).
d. Data Transfer and Validation
- Validation (validation/): Additional Pydantic schemas and cross-validation logic.
e. Utilities (utils/)
- parsers/: Custom logic to parse specific documents (passport, account, profile, description).
- storage/: Manages local storage of decoded game files.
- decisions_makers/: Structured output for LLM calls.
f. External Systems
- Julius Baer Hackathon API (game simulation).
- OpenAI or other LLM provider.
- Tesseract-OCR runtime (local).
g. Persistence
- Local filesystem storage for game files (no relational database).

##### Relationships and Data Flow
- User → Frontend UI: Uploads or views client dossier.
- Frontend → Flask API: REST calls (/new-game, /next, /decision) over HTTP.
- Flask Controller → Services Layer: Passes file references / decision payloads.
- Services:
- extractor.py uses Tesseract-OCR + utils/parsers to produce structured data.
- advisor.py sends extracted data to LLM (via Langchain/OpenAI) for reasoning.
- validation modules apply Pydantic schemas to enforce consistency.
- julius_baer_api_client.py interacts with the hackathon API to fetch new dossiers or submit decisions.
- Services → DTOs: Wrap responses/errors.
- Flask → Frontend: Returns JSON with extracted fields, LLM recommendation, and game status.
- Frontend updates UI, allows user decision.
- User decision → Frontend → Backend → Hackathon API → Local storage updated.

##### Architectural Patterns and Principles
- Layered Architecture:
- Presentation Layer (frontend)
- API Layer (Flask controllers in app.py)
- Service Layer (business logic in services/)
- Utility Layer (parsers, storage)
- Validation Layer (Pydantic schemas)
- Separation of Concerns: Each service handles a single responsibility.
- DTO Pattern: Clear separation between raw request payloads and internal models.
- External Integration: Adapters for OCR, LLM, and external API.

##### Essential Elements
- Clear component boundaries and labels.
- Annotations of data formats and protocols (HTTP JSON, file streams, LLM prompts).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        FrontendUI["Frontend UI<br/>(Alpine.js, Bootstrap, Vite, Mammoth.js)"]:::frontend
        IndexHTML["index.html"]:::frontend
        MainJS["main.js"]:::frontend
        StylesSCSS["styles.scss"]:::frontend
        ViteConfig["vite.config.js"]:::frontend
        PackageJSON["package.json"]:::frontend
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        FlaskAPI["Flask API<br/>(app.py, config.py)"]:::backend
        AppPy["app.py"]:::backend
        ConfigPy["config.py"]:::backend
        OpenAPI["openapi.json"]:::backend
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AdvisorSvc["Advisor Service<br/>(services/advisor.py)"]:::service
        ExtractorSvc["Extractor Service<br/>(services/extractor.py)"]:::service
        JuliusClient["Julius Baer API Client<br/>(services/julius_baer_api_client.py)"]:::service
    end

    %% DTO Layer
    subgraph "DTO Layer"
        direction TB
        RequestsDTO["requests.py"]:::validation
        ResponsesDTO["responses.py"]:::validation
        ErrorsDTO["errors.py"]:::validation
    end

    %% Validation Layer
    subgraph "Validation Layer"
        direction TB
        CrossValidate["cross_validate.py"]:::validation
        PassportVal["from_passport.py"]:::validation
        AccountVal["from_account.py"]:::validation
        ProfileVal["from_profile.py"]:::validation
        DescriptionVal["from_description.py"]:::validation
        LLMVal["llm_validate.py"]:::validation
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        subgraph Parsers
            direction TB
            ParserPassport["passport_parser.py"]:::utils
            ParserAccount["account_parser.py"]:::utils
            ParserProfile["profile_parser.py"]:::utils
            ParserDescription["description_parser.py"]:::utils
        end
        DecisionMaker["llm_call_structured_output.py"]:::utils
        StorageMgr["game_files_manager.py"]:::utils
    end

    %% Persistence
    Storage[(Local File Storage)]:::storage

    %% External Systems
    OpenAI["OpenAI / LLM Provider"]:::external
    Tesseract["Tesseract-OCR Runtime"]:::external
    JuliusAPI["Julius Baer Hackathon API"]:::external

    %% Connections
    FrontendUI -->|Uploads/Views Dossier| FlaskAPI
    FlaskAPI -->|"calls"| AdvisorSvc
    FlaskAPI -->|"calls"| ExtractorSvc
    FlaskAPI -->|"calls"| JuliusClient
    FlaskAPI -->|Uses DTOs| RequestsDTO
    FlaskAPI -->|Uses DTOs| ResponsesDTO
    FlaskAPI -->|Uses DTOs| ErrorsDTO

    ExtractorSvc -->|OCR images| Tesseract
    ExtractorSvc -->|parsing| ParserPassport
    ExtractorSvc -->|parsing| ParserAccount
    ExtractorSvc -->|parsing| ParserProfile
    ExtractorSvc -->|parsing| ParserDescription
    ExtractorSvc -->|returns structured data| AdvisorSvc

    AdvisorSvc -->|LLM prompts| OpenAI
    AdvisorSvc -->|validation| LLMVal
    AdvisorSvc -->|cross-validation| CrossValidate

    JuliusClient -->|HTTP/JSON| JuliusAPI
    JuliusClient -->|stores files| StorageMgr
    StorageMgr -->|file streams| Storage

    FlaskAPI -->|returns JSON| FrontendUI

    %% Click Events
    click FrontendUI "https://github.com/noeberdoz/julius_baer_onboarding/tree/main/frontend/"
    click IndexHTML "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/frontend/src/index.html"
    click MainJS "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/frontend/src/js/main.js"
    click StylesSCSS "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/frontend/src/scss/styles.scss"
    click ViteConfig "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/frontend/vite.config.js"
    click PackageJSON "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/frontend/package.json"
    click AppPy "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/app.py"
    click ConfigPy "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/config.py"
    click OpenAPI "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/openapi.json"
    click AdvisorSvc "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/services/advisor.py"
    click ExtractorSvc "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/services/extractor.py"
    click JuliusClient "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/services/julius_baer_api_client.py"
    click RequestsDTO "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/dto/requests.py"
    click ResponsesDTO "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/dto/responses.py"
    click ErrorsDTO "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/dto/errors.py"
    click CrossValidate "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/validation/cross_validate.py"
    click PassportVal "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/validation/from_passport.py"
    click AccountVal "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/validation/from_account.py"
    click ProfileVal "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/validation/from_profile.py"
    click DescriptionVal "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/validation/from_description.py"
    click LLMVal "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/validation/llm_validate.py"
    click ParserPassport "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/utils/parsers/passport_parser.py"
    click ParserAccount "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/utils/parsers/account_parser.py"
    click ParserProfile "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/utils/parsers/profile_parser.py"
    click ParserDescription "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/utils/parsers/description_parser.py"
    click DecisionMaker "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/utils/decisions_makers/llm_call_structured_output.py"
    click StorageMgr "https://github.com/noeberdoz/julius_baer_onboarding/blob/main/utils/storage/game_files_manager.py"

    %% Styles
    classDef frontend fill:#D0E7FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#DFFFE0,stroke:#22863A,color:#22863A;
    classDef service fill:#FFF5B1,stroke:#DBAB09,color:#735C0F;
    classDef utils fill:#F0F0F0,stroke:#6A737D,color:#24292E;
    classDef validation fill:#F0F0F0,stroke:#6A737D,color:#24292E;
    classDef external fill:#EFEFEF,stroke:#959DA5,color:#959DA5;
    classDef storage fill:#FFEFD5,stroke:#D2691E,color:#D2691E
```
