pfm-ocr/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repo is

An on-premise, GPU-accelerated OCR system that turns a driver's phone photo of a Delivery Order (DO) into structured, database-backed data. A Flutter mobile app (this root) is the field-facing client; a Dockerized backend (backend/) runs the Next.js API gateway, the PaddleOCR/vLLM pipeline, and Postgres.

Read README.md first for the full architecture (mermaid diagrams, tech stack, accuracy numbers). Read backend/CLAUDE.md before touching anything under backend/ — it documents backend-specific history, gotchas, and confidentiality notes not repeated here.

Repository structure

lib/                    # Flutter app (this is the root Dart package)
  config/                 app_config.dart — theme + dynamic API base URL resolution
  core/                   Dio client, Hive storage, geolocation, go_router
  features/               auth, camera, documents, editor, splash — one folder per feature
  models/
test/                   # Flutter widget/unit tests (flat, not mirrored to lib/)
backend/                # Next.js gateway + Python OCR pipeline + Postgres (see backend/CLAUDE.md)
docs/                   # Deep-dive workflow & extraction-rule docs
docker-compose.yml      # Canonical backend stack — always run from repo root, not backend/
docker-compose.demo.yml # Production-mode override (npm start instead of npm run dev)
start-dev-tunnel.ps1    # Syncs LAN IP into app_config.dart + starts ngrok

Two docker-compose.yml files exist (./docker-compose.yml and backend/docker-compose.yml, a legacy standalone duplicate with a different Compose project name). Always run docker compose from the repo root — running it from inside backend/ causes container-name conflicts with anything already started from root.

Commands

Flutter app (repo root)

flutter pub get                 # install deps
flutter run                     # run on connected device/emulator
flutter test                    # run all tests in test/
flutter test test/blur_detector_test.dart   # run a single test file
flutter analyze lib             # static analysis (flutter_lints)
flutter build apk --release     # release APK -> build/app/outputs/flutter-apk/app-release.apk
./start-dev-tunnel.ps1          # detect LAN IP, patch app_config.dart, start ngrok

The release APK is currently debug-signed (android/app/build.gradle.kts has a TODO for a real signing config) — fine for internal installs, not Play Store distribution.

Backend (from repo root)

cp backend/.env.example backend/.env   # first-time setup; set CUDA_VISIBLE_DEVICES
docker compose up --build              # full stack (dev mode, hot-reloads pfm-web-app)
docker compose -f docker-compose.yml -f docker-compose.demo.yml up -d --build   # production mode, rebuild before every demo

See backend/CLAUDE.md for the Next.js app commands (npm run dev/build/lint), the accuracy regression harness, and the uv/vLLM Python service commands.

Architecture notes for the Flutter client

• API base URL is resolved dynamically at startup, not hardcoded to one value: AppConfig.initializeApiBaseUrl() in lib/config/app_config.dart tries a fixed ngrok domain first, falling back to a hardcoded LAN IP. If login/upload fails on a device, this is the first thing to check — re-run start-dev-tunnel.ps1 if the host machine's LAN IP or ngrok tunnel has gone stale.
• Upload flow: capture → Laplacian-variance blur check → GPS tag → multipart upload → the app polls GET /documents every 2s (up to 2 min) until the backend's OCR pass sets parsed=true → operator reviews/corrects on-device → PUT /documents/:id saves final data → PDF receipt generated/printed locally.
• Pending-upload queue is persisted to a Hive box (lib/features/documents/pending_documents_provider.dart, lib/core/storage/local_storage.dart) — an OS-level app kill mid-upload no longer loses the document; on next launch the queue reloads and resumes anything left non-terminal (fixed 2026-07-08, see plans/next-enhancements.md §3.1).
• Auth (lib/features/auth/) talks to a demo-stub backend (single hardcoded admin/password, no real server-side token verification) — don't build on top of it assuming real security.

Confidentiality

backend/ contains real client business data committed to source (SKU/vendor/customer master data, scanned DO photos, hand-labeled ground truth) — see backend/CLAUDE.md's Confidentiality section before exporting, logging, or sharing anything from backend/sources/ or backend/uploads/.

Agents Settings Kit

@AGENTS.md

The rules above are the shared, cross-tool source of truth for the e/enhance and n/next enhancement workflow — kept in AGENTS.md, not duplicated here, so Cursor/Copilot/other agents stay in sync (see docs/vibe-coding/ if that directory is added later). Roles referenced above are defined in SKILLS.md. The workflow's backlog and shipped-feature log live in plans/next-enhancements.md and docs/feature-list.md respectively — see AGENTS.md's Adaptation Notes for how those coexist with this repo's pre-existing .agents/AGENTS.md (OCR parsing rules) and plans/next-enhancement-plan.md (a separate, already-[DONE] QA checklist).

Scope: this kit excludes backend/. AGENTS.md's "Scope" section (top of the file) is authoritative — the e/n workflow, its §3 file-size enforcement, and its §5/§6 Demo-Live/Cloud-Local switches apply to the Flutter app only. backend/ keeps its own pre-existing backend/CLAUDE.md + backend/AGENTS.md; don't run e/n against backend modules or apply this kit's generic rules there unless the user explicitly asks for a backend-scoped run.

Claude-specific notes:

• Role subagents: when a task benefits from a fresh, unbiased pass — code review, QA verification, architecture check — spawn the relevant SKILLS.md role via the Agent tool instead of continuing in the current context. This mirrors the "review in a fresh context window" practice: a context that has been implementing a feature is a worse reviewer of that same feature.
• Clarifying questions (AGENTS.md §2a): use AskUserQuestion for the one-at-a-time grilling step, not free-text questions buried in a longer response.
• Plan mode: for any n/next task that touches multiple files or has more than one reasonable implementation approach, use EnterPlanMode before writing code.