Veracia (VeRA)

A document workflow system for the Vietnamese public sector.

Veracia helps government offices handle paper documents faster and more safely. It reads incoming documents, classifies them, routes them to the right department, and writes a short summary. Officers stay in control of every decision that matters. Every action is recorded in an audit trail.

Veracia is not a chatbot. It is a workflow tool that supports officers.

---

The problem

Government offices in Vietnam work with paper every day. Letters, petitions, reports, decisions, and contracts arrive as physical documents or phone photos. Each one must be read, understood, sent to the right department, and tracked across the office.

This work is slow and creates three common problems:

1. Wrong routing. A document lands in the wrong department and is lost for days.
2. Heavy workload. Officers spend hours on simple reading and sorting.
3. Missing records. When a decision is questioned later, there is no clear record of who saw what and when.

Veracia addresses these three problems.

What Veracia does

1. Reads the document. Accepts scans, PDFs, or phone photos. Extracts the text in Vietnamese.
2. Classifies it. Determines the document type (letter, report, petition, and so on) and the security level (Public, Internal, Confidential, or Top Secret).
3. Routes it. Sends the document to the correct department based on a clear mapping table.
4. Summarises it. Produces a short summary with subject, sender, request type, deadline, and required action.
5. Records everything. Every AI and human action is saved in an audit trail with a timestamp, the actor, and a reason.

Five rules the system never breaks

These rules are enforced in the code, not in the interface.

1. Sensitive documents pause for a human. Any document marked Confidential or Top Secret is not routed automatically. An officer must confirm first.
2. Low confidence pauses for a human. If the classifier is less than 70% sure, the document waits for human review.
3. The original is never changed. The uploaded file is preserved as it was received. Results and decisions are added on top.
4. Every decision is logged. Classification, routing, summarisation, approval, and override are saved with time, actor, and reason.
5. Humans have the final say. When an officer disagrees with the AI, they can override it. Both the AI's choice and the human's choice are saved, side by side.

How it works

  Document uploaded
        │
        ▼
   Qwen-VL reads the document (OCR + understanding)
        │
        ▼
   Qwen-VL classifies it (type + security + confidence)
        │
        ▼
   Router sends it to the correct department
        │
        │   If Confidential or Top Secret, pause for officer confirmation.
        │   If confidence is below 70%, pause for human review.
        │
        ▼
   Qwen-turbo writes a structured summary
        │
        ▼
   Every step is recorded in the audit trail

Qwen models

Stage	Model	Role
Read the document	Qwen-VL	Reads phone photos and scans. Returns Vietnamese text.
Classify and grade	Qwen-VL	Returns document type, security level, confidence, and reasoning.
Write the summary	Qwen-turbo / plus	Returns subject, sender, request type, urgency, and deadline.

Both models are accessed through the OpenAI-compatible DashScope endpoint. Qwen-VL is the primary model because it handles reading, understanding, and classification in a single call, which fits the messy reality of physical government documents.

Tech stack

• Frontend: React 19, Vite, TypeScript, Tailwind, shadcn/ui.
• Backend: FastAPI, Python 3.12.
• AI: Qwen-VL and Qwen-turbo/plus, via DashScope.
• Storage: JSON files. No database is used in the current build.
• Authentication: None. Hardcoded roles (clerk, officer, senior officer).

Canonical repo references:

• docs/VeRA_backend_docs.pdf
• docs/SENIOR_PROMPT.md
• docs/mermaid/vera_flow_v1_1_ubnd_approved.mermaid
• docs/PRD.md

All other project docs live under docs/.

Running locally

Requirements: Python 3.12, Node.js 20, and a DashScope API key.

cp .env.example .env
# Fill in DASHSCOPE_API_KEY and DASHSCOPE_BASE_URL

make install
make dev

For a single-process build:

make build
make run

Then open http://localhost:8000 and upload a document.

Roadmap

Veracia's full vision is a seven-step workflow for government document handling. The current build implements Steps 0 to 3 (intake, classification, routing, summarisation). Steps 4 to 7 are planned next:

• Step 4. Each department adds comments in its own section. Originals are never changed.
• Step 5. The AI consolidates all comments into one report. Agreements and conflicts are shown separately.
• Step 6. The report flows through signatories in hierarchical order. Each signature is timestamped.
• Step 7. Signed documents are dispatched to executing units, archived by security level, and sealed against further edits.

The current architecture supports these additions without structural changes.

---

Veracia. Built for physical documents. Built for Vietnamese government. Built to support officers.