3. System Architecture

3.1 Architecture Patterns

3.1.1 Layered Architecture

The system follows a strict 4-layer architecture:

Layer 1: Presentation Layer

• Electron Desktop Application (React + TypeScript + Tailwind CSS)
• Responsibilities:
  • User interface rendering
  • User input validation
  • State management (React Context)
  • API communication
  • Local storage management
  • Dark mode theming
  • Multi-language display

Layer 2: Application/API Layer

• FastAPI Backend Service
• Responsibilities:
  • RESTful API endpoints
  • Request validation (Pydantic)
  • Business logic orchestration
  • Authentication & authorization (future)
  • Rate limiting (future)
  • Logging & monitoring
  • File upload handling
  • OCR processing coordination

Layer 3: Domain/Core Services Layer

• Pure Python Core Engine
• Responsibilities:
  • Denomination calculation algorithms
  • Currency conversion logic
  • Optimization strategies
  • FX rate management
  • Data models & validation
  • Alternative generation
  • Mathematical operations

Layer 4: Infrastructure Layer

• SQLite Database, File System, External Dependencies (Tesseract, Poppler)
• Responsibilities:
  • Data persistence
  • File storage
  • OCR services
  • PDF processing
  • Configuration management

3.1.2 Repository Pattern

Purpose: Separate data access logic from business logic

Benefits:

• Database implementation can be swapped (SQLite ? PostgreSQL)
• Easy to mock for testing
• Clear separation of concerns

3.1.3 Service Pattern

Purpose: Encapsulate business logic in reusable services

Example: OCR Processor Service handles all text extraction logic independently

3.1.4 Strategy Pattern

Purpose: Implement different optimization algorithms

The system supports multiple calculation strategies (greedy, balanced, minimize large/small) using the Strategy pattern, allowing runtime algorithm selection.

3.2 Data Flow Diagrams

3.2.1 Single Calculation Flow

User Input ? Electron UI ? API Call ? FastAPI Endpoint ? Core Engine
                  ?
       Save to Database (if enabled)
                  ?
       Return Response ? Display Results + Update History

3.2.2 Bulk Upload Flow

File Selection ? Validation ? FormData ? HTTP POST /bulk-upload
                  ?
       File Type Detection ? Route to Processor
                  ?
       CSV/PDF/Word/Image Processor ? Extract Rows
                  ?
       Apply Smart Defaults ? For Each Row: Calculate
                  ?
       Collect Results ? Return Summary + Details

3.2.3 OCR Processing Flow

Image/PDF Upload ? OCRProcessor ? File Extension Check
                  ?
       Image (.jpg/.png) ? Tesseract OCR
       PDF (.pdf) ? PyMuPDF (text) OR pdf2image + Tesseract (scanned)
       Word (.docx) ? python-docx
                  ?
       Extract Text ? Parse to Rows ? Smart Extraction
                  ?
       Return Structured Data ? Continue to Calculation

3.3 Component Interaction Diagram

FRONTEND (Electron + React)
  +-- Calculator Page
  +-- History Page
  +-- Bulk Upload Page
  +-- Settings Page
      ? HTTP/REST
BACKEND (FastAPI)
  +-- Calculations API
  +-- History API
  +-- Settings API
  +-- OCR Processor Service
      +-- Tesseract (Images)
      +-- PyMuPDF (PDFs)
      +-- python-docx (Word)
      ?
INFRASTRUCTURE
  +-- Core Engine (Python)
  ¦   +-- Denomination Calculations
  +-- SQLite Database
      +-- Calculations History
      +-- Settings