ComplyPilot RefundShield

VAT Compliance & Evidence Autopilot for Sri Lanka's VAT-registered businesses

ComplyPilot helps any VAT-registered business find invoice, supplier, VAT-schedule and Customs-evidence blockers before filing. It provides an explainable refund-readiness score, a prioritised action plan, a statutory 45-day clock scenario and a complete human-reviewed audit trail.

ComplyPilot does not predict the Inland Revenue Department's official Low/Medium/High risk category and does not guarantee a VAT refund date. The score is a transparent internal readiness proxy.

Run the application

The working application is a Next.js App Router project. Requires Node.js 20 or later and a Postgres database (run state - extracted invoices, findings, reconciliation - is stored there, not in process memory, so it survives a restart and stays isolated per browser session).

npm install
cp .env.example .env.local   # then add your Model Studio key
docker compose up db         # starts just Postgres, published on localhost:5433
npm run dev                  # http://localhost:3000

Production build:

npm run build
npm start

Run with Docker Compose

Docker Compose runs the production standalone build and includes the Chromium runtime required by the Playwright GUI filing agent.

# Optional: create .env for live Qwen or MuleRun credentials.
# The app also runs honestly in demo/local mode without these values.
cp .env.example .env

docker compose up --build
# open http://localhost:3000

Stop the application with docker compose down. Set APP_PORT=8080 in .env if port 3000 is already occupied. Keep GUI_AGENT_HEADLESS=true inside Docker; run the app directly on the host if you need a visible Playwright browser window. The Compose service passes secrets at runtime and does not bake them into the image.

ComplyPilot-RefundShield-UI-Demo.html remains in the repository as the original static visual reference. DEVELOPMENT_AGENT_BRIEF.md holds the implementation contract, API shape and acceptance checklist.

Environment variables

Copy .env.example to .env.local. Never commit a populated env file.

Variable	Purpose
APP_PORT	Host port exposed by Docker Compose; defaults to 3000.
DATABASE_URL	Postgres connection string for run state. Required; no in-memory fallback.
POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB / POSTGRES_PORT	Only used by the db Compose service; POSTGRES_PORT defaults to 5433 so it never fights another project's Postgres for the default port.
DASHSCOPE_API_KEY	Model Studio API key. Read server-side only.
DASHSCOPE_BASE_URL	OpenAI-compatible endpoint. Differs by region.
QWEN_MODEL	Vision-language model id used for invoice extraction.
QWEN_CHAT_MODEL	Text model used by the grounded Data Copilot.
GUI_AGENT_HEADLESS	Keep true in Docker; use false for a visible host browser.
WORKFLOW_MODE	local or mulerun.
MULERUN_API_URL	Published MuleRun workflow webhook.
MULERUN_API_KEY	Bearer token for the MuleRun workflow.

Without a key the application still runs: every response is clearly labelled DEMO FALLBACK in the header and the reason is written to the audit trail. The demo never presents fixture data as a live model response.

Live extraction vs demo fallback

Model Studio is called only when a document is uploaded through the evidence dropzone. The header badge shows LIVE QWEN when a live extraction succeeded and DEMO FALLBACK otherwise, with the specific reason on hover.

Supported uploads are JPEG, PNG, WebP and BMP images, up to 10 MB. PDFs must be rendered to an image first; a PDF upload is rejected with an explanation rather than being silently mislabelled.

Grounded Data Copilot

The floating Ask your data chatbox answers from the latest session-isolated analysis run: readiness score, findings, structured invoice extraction, VAT Schedule reconciliation and the bundled official-source summaries. It never sends the raw invoice image to the chat endpoint. With DASHSCOPE_API_KEY configured it uses QWEN_CHAT_MODEL; otherwise it returns clearly labelled deterministic demo answers. Source links are selected from the application's allow-listed government data pack, not from model-generated URLs. Answers remain decision support and are not tax advice or an official IRD conclusion.

Workflow: MuleRun or local

WORKFLOW_MODE decides how the pre-flight runs.

Mode	Behaviour	Header badge
local (default)	Only the in-process orchestrator runs.	Workflow: LOCAL FALLBACK
mulerun	The extracted case is posted to the MuleRun webhook. If it fails or times out, the local orchestrator still produces the result.	Workflow: LIVE MULERUN or LOCAL FALLBACK

The invoice image is never sent to MuleRun. Qwen extraction happens in this application and only the structured result crosses the boundary.

MuleRun findings are advisory. Its statuses are compared against the local findings and any disagreement is shown in the trace, but they are never applied. A blocker counts as resolved only because a human resolved it, and the score is always computed by lib/rules/scoring.ts. Accepting a remote status would let anything able to answer the webhook award points, which would make the score meaningless.

Status: the adapter is implemented and verified end to end against a stub webhook, including the failure path. It has not yet run against a published MuleRun workflow.

GUI filing agent

The readiness score is a gate, not the end of the journey. Once every blocker is resolved and an authorised human ticks the approval box, a GUI agent completes the filing by operating a portal on screen rather than calling an API.

여기까지가 README 앞부분입니다. 나머지는 원문에서 읽을 수 있습니다. README 전문 보기 ↗