Document vault¶

The Vault gives a high-assurance citizen quick access to supported government-document copies. Objects are private and owner-scoped.

Supported prototype document types¶

Allowed content types are PDF, JPEG, and PNG. The configured default maximum is 8 MiB.

Upload path¶

Flutter file picker
  → local size and format check
  → multipart POST /api/v1/documents
  → backend validates document code
  → reads at most configured limit + 1 byte
  → validates file signature and MIME type
  → uploads to randomized owner-scoped private object path
  → stores safe metadata
  → refreshes journey evidence

The citizen-facing required-document row opens a detail page containing backend-provided “Why it matters” and “How to add it” guidance.

List and open documents¶

GET /documents returns owner-safe summaries. The client requests a short-lived signed URL through:

POST /api/v1/documents/{document_id}/signed-url

Storage paths, service keys, and object hashes are never returned as ordinary list metadata.

Journey evidence¶

A vault file does not automatically prove an official fact. Evidence distinguishes:

• available document;
• active document;
• verification status; and
• allowlisted record attributes relevant to a requested change.

AI-extracted fields are marked AI_EXTRACTED_UNVERIFIED and require citizen confirmation before use.

Operator seeding¶

Authorized demo operators can seed a synthetic document after identifying the backend user UUID:

cd backend
.\.venv\Scripts\python.exe -m scripts.seed_government_document `
  --owner-user-id USER_UUID `
  --file C:\synthetic\driver-license.pdf `
  --document-code DRIVER_LICENSE `
  --agency-code LTO

Never use a real government document in the hackathon demo.

Supabase setup¶

Apply the idempotent schema migration:

cd backend
.venv/Scripts/python.exe -m scripts.apply_supabase_migrations

The preferred database variable is SUPABASE_DATABASE_URL. The historical misspelling SUPABSE_URI remains accepted for compatibility.