This repository contains the consolidated codebase for Prima Fresh Mart Scanner v2, featuring a Flutter mobile client and an on-premise AI OCR backend for processing delivery orders.

Architecture Overview

                        [ Flutter Mobile App (Frontend) ]
                                        │
                                        ▼
┌─────────────────────────────── Nginx Router (8000) ────────────────────────────────┐
│                                       │                                            │
│            ┌──────────────────────────┴──────────────────────────┐                 │
│            ▼                                                     ▼                 │
│  [ Next.js API Gateway (3000) ]                               [ vLLM VLM Server (8118) ]
│      │               │                                                             │
│      ▼               ▼                                                             │
│  [ Postgres ]   [ Pipeline API (8090) ]                                            │
│                      │                                                             │
│                      ▼                                                             │
│                 [ GPU Model Engine ]                                               │
└────────────────────────────────────────────────────────────────────────────────────┘

The system comprises two main components:

Frontend: A Flutter mobile application designed for document capture, image quality check (blur detection), offline caching, manual correction, and final PDF generation.
Backend: An on-premise, GPU-accelerated OCR stack wrapped in a unified Docker Compose configuration.

1. Backend Setup & Execution

The backend contains the database, API gateway, preprocessing pipeline, and model inference servers.

Prerequisites

Linux with NVIDIA GPU (CUDA 12.6+ driver, compute capability CC ≥ 8.0 recommended)
Docker & NVIDIA Container Toolkit
Node.js v20+ (optional, for running offline test suites)

Setup & Startup

Configure Environment Variables: Copy .env.example to .env in the ./backend directory and adjust values as needed:
```
cp backend/.env.example backend/.env
```
Note: Ensure CUDA_VISIBLE_DEVICES matches the index of your GPU.
Launch Services: Start the entire backend stack with Docker Compose from the root directory:
```
docker compose up --build
```
Verify API Status: Ensure Nginx and the Next.js API server are responding properly by opening the following URLs:
- Next.js API Status: http://localhost:3000 (or through Nginx at http://localhost:8000)
- Pipeline Health: http://localhost:8000/health
- vLLM Models List: http://localhost:8000/v1/models

Database Migrations

PostgreSQL initialization and migrations are applied automatically during first startup. SQL scripts are located in ./backend/db/migrations and are run in lexicographical order.

TDD Unit Verification

To verify the Next.js document parsing rules (fused PO correction, date cleaning, etc.) locally without running the docker stack, run:

npx tsx backend/pfm-web-app/src/utils/parser.test.ts

2. Frontend Setup & Execution

The mobile application is built using Flutter and connects to the backend API.

Prerequisites

Flutter SDK (version >=3.2.0 <4.0.0)
Android Studio / Xcode for emulators and SDK configurations

Setup & Startup

Install Dependencies: Get the Flutter packages:
```
flutter pub get
```
Configure API URL: Verify the backend API endpoint configuration in lib/config/app_config.dart:
```
static const String apiBaseUrl = 'http://<your-backend-ip>:3000/api/v1';
```
Run Application: Launch the app on a connected emulator or physical device:
```
flutter run
```

Project Structure

.
├── backend/                       # On-Premise OCR Backend Services
│   ├── config/                    # Pipeline & VLLM YAML configurations
│   ├── db/                        # Database migration scripts & ERD docs
│   ├── pfm-web-app/               # Next.js API Gateway (excluding UI pages)
│   ├── scripts/                   # Startup bash scripts
│   ├── sources/                   # SKU master sheets and CSV assets
│   ├── Dockerfile                 # Multi-stage GPU Dockerfile for backend components
│   └── nginx.conf                 # reverse proxy & routing configurations
├── lib/                           # Flutter Frontend Core Files
│   ├── config/                    # Global app configuration & theme variables
│   ├── core/                      # Core network (Dio), local storage (Hive), and routing
│   ├── features/                  # Feature modules (Auth, Camera, Documents list, Editor)
│   └── models/                    # Document & items model definitions
├── test/                          # Flutter UI and logic unit tests
├── docker-compose.yml             # Unified Compose stack file
└── README.md                      # Project manual