OpenDA — AI Disbursement Account Analyzer

Open-source Human-in-the-Loop AI platform for maritime port agency cost validation.
Accountants upload a Proforma DA (JSON) + Final DA (PDF). An LLM extracts every line item, flags deviations, and generates a full audit trail — all without lock-in to a specific AI provider.

---

Maritime DA Workflow — Where OpenDA Fits

flowchart TD
subgraph PORT ["Port Operations"]
V[Vessel Arrives at Port]
V --> SVC["Port Agent Provides Services\npilotage · towage · berth · provisions · crew"]
SVC --> FDA_DOC["Port Agent Issues FDA\nFinal Disbursement Account"]
end
subgraph OWNER ["Ship Owner / Operator"]
FDA_DOC --> RECV["Receives FDA + PDA Proforma Estimate"]
RECV --> TRAD["Traditional Approach\n── manual line-by-line comparison ──\n⚠ error-prone · days to complete\n⚠ no audit trail · no provider lock-in"]
end
subgraph OPENDA ["OpenDA — AI-Assisted DA Validation"]
direction TB
UP["① Accountant Uploads\nPDA JSON + FDA PDF"]
EXT["② AI Extraction Docling + LLM\nPDF parsed into structured line items + bounding boxes"]
DEV["③ Deviation Engine\nPDA vs FDA comparison · flags HIGH_DEVIATION,\nLOW_CONFIDENCE, MISSING lines"]
ACCT["④ Accountant Review UI\nAI-highlighted deviations overlaid on PDF\nAccept, annotate or reject each item"]
OPS["⑤ Operator Approval UI\nFinal sign-off with remarks"]
AUD["⑥ Immutable Audit Trail\nEvery decision logged with actor + timestamp"]
UP --> EXT --> DEV --> ACCT --> OPS --> AUD
end
RECV -- "replaces" --> UP
TRAD -. "eliminated by OpenDA" .-> UP
AUD --> ERP["ERP / VMS System\nWebhook push on approval"]
ERP --> FIN(["DA Settled & Archived ✓"])

Loading

---

Architecture

flowchart TD
A[Accountant Browser\nport :3000] -->|upload PDA JSON + FDA PDF| B[FastAPI :8000\nPOST /api/v1/da/upload]
B -->|enqueue| C[Redis :6379]
C -->|async task| D[Celery Worker]
D -->|parse PDF| E[Docling]
E -->|structured text + BBoxes| D
D -->|extract JSON| F[LiteLLM Gateway]
F -->|route to active provider| G{LLM Provider}
G -->|Anthropic Claude| G
G -->|OpenAI GPT-4o| G
G -->|Google Gemini| G
G -->|Ollama local| G
F -->|FDASchema| D
D -->|compare PDA vs FDA| H[Deviation Engine]
H -->|DeviationReport| I[(PostgreSQL :5432)]
I -->|PENDING_ACCOUNTANT_REVIEW| A
A -->|review + annotate| J[PUT /submit-to-operator]
J -->|PENDING_OPERATOR_APPROVAL| K[Operator Browser\nport :3001]
K -->|approve| L[POST /approve]
L -->|webhook| M[ERP / VMS]
L -->|PUSHED_TO_ERP| I

Loading

---

Quick Start

Prerequisites

Tool	Version
Docker + Docker Compose	24+
Python	3.12+
UV	latest
Node.js	20+
pnpm	9+

1. Clone & Configure

git clone https://github.com/your-org/openda.git
cd openda
cp .env.example .env

Edit .env and set your LLM provider:

# Choose ONE provider block:# Anthropic Claude (recommended)
LLM_MODEL=anthropic/claude-sonnet-4-6-20250514
LLM_API_KEY=sk-ant-...
# Google Gemini# LLM_MODEL=gemini/gemini-2.0-flash# LLM_API_KEY=AIza...# OpenAI# LLM_MODEL=openai/gpt-4o# LLM_API_KEY=sk-proj-...# Ollama (no API key needed)# LLM_MODEL=ollama/llama3.3# LLM_API_KEY=ollama

2. Docker (full stack)

docker compose up --build

Service	URL
Accountant UI	http://localhost:3000
Operator UI	http://localhost:3001
API	http://localhost:8000
API docs	http://localhost:8000/docs

3. Local Development

Backend (Python)

cd backend
uv venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"# start postgres + redis
docker compose up -d postgres redis
# migrate
alembic upgrade head
# run API
uvicorn main:app --reload --port 8000
# run Celery worker (separate terminal)
celery -A app.workers.celery_app worker --loglevel=info

Frontend

# Accountant UI (port 5173, proxies /api → :8000)cd frontend-accountant && pnpm install && pnpm dev
# Operator UI (port 5174)cd frontend-operator && pnpm install && pnpm dev

---

LLM Provider Reference

OpenDA uses LiteLLM as a universal gateway. Switch providers by changing two env vars — zero code changes required.

Provider	LLM_MODEL	LLM_API_KEY
Anthropic Claude	anthropic/claude-sonnet-4-6-20250514	Anthropic API key
Google Gemini	gemini/gemini-2.0-flash	Google AI Studio key
OpenAI	openai/gpt-4o	OpenAI API key
Azure OpenAI	azure/gpt-4o	Azure API key
Ollama (local)	ollama/llama3.3	ollama

For Ollama, also set OLLAMA_API_BASE=http://localhost:11434.

---

API Reference

Method	Path	Description
POST	/api/v1/da/upload	Upload PDA JSON + FDA PDF, starts AI processing
GET	/api/v1/da/{id}/status	Poll DA lifecycle status
GET	/api/v1/da/{id}/deviation-report	Full deviation report with per-item flags
GET	/api/v1/da/{id}/audit-log	Immutable audit trail
PUT	/api/v1/da/{id}/submit-to-operator	Accountant submits reviewed items
POST	/api/v1/da/{id}/approve	Operator approves → fires ERP webhook
POST	/api/v1/da/{id}/reject	Reject at any review stage
GET	/api/v1/health	Health check (DB + Redis + LLM config)

Full interactive docs: http://localhost:8000/docs

---

Deviation Flags

Flag	Condition
HIGH_DEVIATION	Absolute variance > $500 or percentage variance > 10%
LOW_CONFIDENCE	AI extraction confidence < 0.85
MISSING_PDA_LINE	FDA item has no matching PDA category
MISSING_FROM_FDA	PDA item absent from FDA

---

ERP Webhook

When an operator approves a DA, OpenDA fires a POST to WEBHOOK_URL with:

{
"da_id": "uuid",
"port_call_id": "PC-2024-SGSIN-0001",
"status": "APPROVED",
"total_estimated": 12500.00,
"total_actual": 13050.00,
"operator_remarks": "Anchorage fees validated against port authority receipt",
"llm_provider": "anthropic/claude-sonnet-4-6-20250514",
"approved_at": "2025-01-15T09:32:00Z"
}

Set WEBHOOK_URL=http://your-erp/api/inbound/disbursement in .env.
For local testing: WEBHOOK_URL=http://localhost:8000/api/v1/da/webhook-echo

---

DA Lifecycle

stateDiagram-v2
direction LR
[*] --> UPLOADING : accountant uploads PDA JSON + FDA PDF
UPLOADING --> AI_PROCESSING : file stored, Celery task enqueued
AI_PROCESSING --> AI_PROCESSING : retry on transient LLM failure
AI_PROCESSING --> PENDING_ACCOUNTANT_REVIEW : deviation report generated
AI_PROCESSING --> REJECTED : unrecoverable extraction error
PENDING_ACCOUNTANT_REVIEW --> PENDING_OPERATOR_APPROVAL : accountant reviews & submits
PENDING_ACCOUNTANT_REVIEW --> REJECTED : accountant rejects DA
PENDING_OPERATOR_APPROVAL --> APPROVED : operator approves
PENDING_OPERATOR_APPROVAL --> REJECTED : operator rejects
APPROVED --> PUSHED_TO_ERP : ERP webhook fired
PUSHED_TO_ERP --> [*]
REJECTED --> [*]

Loading

---

Testing

cd backend
# Generate synthetic test fixtures (5 PDA JSONs + 5 FDA PDFs)
python ../test_data/generate_fixtures.py
# Run schema smoke tests
python ../test_data/smoke_test_schemas.py
# Run pytest suite
pytest tests/ -v

---

Project Structure

openda/
├── backend/ # FastAPI + Celery + SQLAlchemy
│ ├── app/
│ │ ├── api/routes/ # da.py, health.py
│ │ ├── models/ # SQLAlchemy ORM models
│ │ ├── schemas/ # Pydantic v2 schemas (PDA, FDA, deviation)
│ │ ├── services/ # llm_provider, extraction_service, deviation_engine, state_machine
│ │ └── workers/ # Celery app + tasks
│ ├── alembic/ # DB migrations
│ └── main.py
├── frontend-accountant/ # React + Vite (split-screen PDF review)
├── frontend-operator/ # React + Vite (approval dashboard)
├── test_data/ # Synthetic PDA/FDA fixtures
├── docker-compose.yml
└── .env.example

---

Contributing

1. Fork → feature branch → PR against main
2. Run ruff check . and mypy before pushing
3. Add tests for any new business logic in backend/tests/

---

License

MIT — see LICENSE