How noeberdoz/julius_baer_onboarding works
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).