2. Project Overview

2.1 Problem Statement

Challenges

• Manual calculation errors: Humans make mistakes when counting large amounts of money, especially with multiple denominations
• Time-consuming process: Manually calculating optimal denomination breakdowns for bulk amounts takes significant time
• Lack of optimization: No easy way to find the most efficient combination of notes and coins
• Multiple currency support: Need to handle different currencies with different denominations
• Data extraction from documents: Financial documents contain amounts in various formats (PDFs, images, tables)
• Bulk processing requirement: Processing hundreds of amounts manually is impractical

Solutions

• Automated calculation: Software-based denomination calculator with 100% accuracy
• Instant results: Sub-100ms calculation time for amounts up to trillions
• Multiple optimization strategies: Greedy, balanced, minimize large/small modes
• Multi-currency engine: Support for INR, USD, EUR, GBP with extensible architecture
• OCR integration: Extract amounts from scanned documents, PDFs, and images using Tesseract
• Bulk upload system: Process CSV files and documents with hundreds of amounts in seconds

2.2 Technology Stack

Frontend Technologies

Backend Technologies

Core Engine Technologies

2.3 Project Structure

The project follows a monorepo structure with three main packages:

f:\Curency denomination distibutor original\
├── packages/
│   ├── core-engine/           # Python calculation engine
│   │   ├── __init__.py
│   │   ├── engine.py          # Main calculation logic (500+ lines)
│   │   ├── fx_service.py      # Foreign exchange rates
│   │   ├── optimizer.py       # Optimization strategies
│   │   ├── models.py          # Data models
│   │   ├── verify.py          # Engine verification tests
│   │   ├── test_engine.py     # Unit tests
│   │   ├── requirements.txt   # Python dependencies
│   │   └── config/
│   │       ├── currencies.json
│   │       └── fx_rates_cache.json
│   │
│   ├── desktop-app/           # Electron frontend
│   │   ├── electron/          # Electron main process
│   │   │   ├── main.ts        # Main process entry
│   │   │   ├── preload.ts     # Preload script
│   │   │   └── window.ts      # Window management
│   │   ├── src/               # React application
│   │   │   ├── App.tsx        # Main app component
│   │   │   ├── main.tsx       # React entry point
│   │   │   ├── components/    # React components
│   │   │   │   ├── CalculatorPage.tsx    (450 lines)
│   │   │   │   ├── HistoryPage.tsx       (380 lines)
│   │   │   │   ├── BulkUploadPage.tsx    (695 lines)
│   │   │   │   └── SettingsPage.tsx      (280 lines)
│   │   │   ├── contexts/      # React contexts
│   │   │   │   ├── LanguageContext.tsx
│   │   │   │   └── ThemeContext.tsx
│   │   │   ├── api/           # API client
│   │   │   │   └── client.ts  # HTTP client
│   │   │   ├── types/         # TypeScript types
│   │   │   └── locales/       # Translation files
│   │   ├── package.json
│   │   ├── vite.config.ts
│   │   ├── tailwind.config.js
│   │   └── tsconfig.json
│   │
│   └── local-backend/         # FastAPI backend
│       ├── app/
│       │   ├── main.py        # FastAPI application
│       │   ├── api/           # API endpoints
│       │   │   ├── calculations.py     (530 lines)
│       │   │   ├── bulk.py             (420 lines)
│       │   │   ├── ocr.py              (350 lines)
│       │   │   ├── history.py          (280 lines)
│       │   │   └── settings.py         (150 lines)
│       │   ├── services/      # Business logic
│       │   │   ├── ocr_processor.py    (645 lines)
│       │   │   └── smart_defaults.py   (180 lines)
│       │   ├── db/            # Database
│       │   │   ├── database.py
│       │   │   └── models.py
│       │   ├── utils/         # Utilities
│       │   │   └── logger.py
│       │   └── locales/       # Translation files
│       │       ├── en.json
│       │       ├── hi.json
│       │       ├── es.json
│       │       ├── fr.json
│       │       └── de.json
│       ├── requirements.txt
│       └── install_dependencies.ps1
│
├── check/                     # Installation scripts
│   ├── install_dependencies.ps1
│   ├── check_dependencies.ps1
│   └── start_with_auto_install.ps1
│
├── documentation/             # Project documentation
│   ├── COMPLETE_PROJECT_DOCUMENTATION.md  (8071 lines)
│   ├── QUICK_REFERENCE.md
│   ├── BULK_UPLOAD_USER_GUIDE.md
│   └── OCR_VERIFIED_WORKING.md
│
├── README.md                  # Project README
└── start.ps1                  # Quick start script

Key Statistics

2.4 Operating Modes

Desktop Mode (Offline-First)

• Architecture: Electron app with embedded FastAPI backend
• Data Storage: Local SQLite database
• Network: No internet required for core functionality
• Performance: Ultra-fast (local processing)
• Use Cases: Banking terminals, accounting offices, offline environments

Web Mode (Future)

• Architecture: React SPA with cloud backend
• Data Storage: Cloud database
• Network: Internet required
• Performance: Fast (network latency applies)
• Use Cases: Cross-device access, team collaboration

API Mode (Future)

• Architecture: RESTful API endpoints
• Data Storage: Shared or isolated
• Authentication: API key based
• Use Cases: Integration with other systems, third-party access