Wida is an open-source ASP.NET Core API for uploading documents, recording invoices and line items, and tracking invoice analysis with Azure Document Intelligence. It targets .NET 10, stores application data in PostgreSQL through Entity Framework Core, and stores uploaded originals either locally or in private Supabase Storage.
| Guide | Contents |
|---|---|
| Setup and development | Prerequisites, local configuration, running the API, migrations, and verification. |
| API reference | Routes, request and response fields, validation, status values, and processing behavior. |
| Google sign-in | OAuth setup, invited users, session protection and document ownership. |
| Architecture | Project responsibilities, dependencies, data relationships, and persistence. |
| Deployment | Hosting checklist and operational verification. |
| Render + Vercel | Docker, Supabase, hosted RabbitMQ, environment variables and troubleshooting. |
| Public beta | Credits, roles, retention and client-IP trust. |
| Processing queue | Broker configuration, admission and recovery. |
| HTTP requests | Requests to run individually in an editor with .http support after setup. |
- Upload PDF/PNG/JPEG/TIFF files (ordinary users: 4 MiB and two pages), retrieve metadata, and preview/download originals with byte-range support.
- Load a bounded document workspace with saved invoices and latest extraction runs.
- Create, update, list, and retrieve one invoice per document, with optional line items and field-specific validation errors. Create/update checks for same-owner supplier and invoice-number duplicates, returning reviewable matches with an explicit override. Identical uploads reuse existing documents and report that outcome to clients.
- Record a manual processing run or request Azure's
prebuilt-invoiceanalysis. - Retrieve processing status, extracted fields, confidence scores, and failure information. New Azure results include source polygons and matching page dimensions for header and line-item highlights; no database migration is needed.
- Inspect the API through OpenAPI and Scalar in Development with an authenticated session.
Analysis is queued durably in RabbitMQ and processed by a .NET background worker. The endpoint returns 202 immediately; clients poll the run for completion. See queue setup and recovery. It records extracted fields and updates unsaved documents through processing/review/failure states. Saving invoice data sets Saved; reanalysis preserves that state even when saving occurs while extraction is still running. Analysis extracts invoice headers and line items but does not create an invoice. The API has no approval or export endpoints; the companion frontend exports loaded invoice headers as CSV. The API requires a Google-backed Wida session and restricts each user to their own documents. See Google sign-in and pilot access.
Clone this repository for the backend. The companion frontend provides the browser workspace and an independent demo.
You need the .NET 10 SDK and a PostgreSQL database. Invoice analysis also requires an Azure Document Intelligence endpoint and API key; reading processing runs and creating manual runs do not. Follow the local setup guide to configure User Secrets, restore dependencies, apply migrations, configure Google pilot access, and start the HTTP profile for the local frontend.
The local HTTP profile uses http://localhost:5085; the optional HTTPS profile also exposes https://localhost:7127. Sign in through the frontend before using protected data routes. Development API documentation is available at /scalar/v1 and /openapi/v1.json on the selected API origin and is also covered by the authenticated-user policy. The request examples illustrate payloads; add session cookies and a CSRF token before sending mutations.
To build and run the automated tests from the repository root:
dotnet build Wida.slnx
dotnet test Wida.slnxWida.Tests exercises the analysis workflow with Azure response fixtures, SQLite for transactional processing/concurrency tests, and EF InMemory for the remaining service fixtures. The build check also describes verification against your own PostgreSQL database and Azure resource.
For the single-container free beta (API + embedded worker on Render, Supabase persistence and hosted RabbitMQ), follow the Render setup and secrets guide. The repository includes a Dockerfile, Render Blueprint and production environment example.
Read CONTRIBUTING.md for issue reports, development checks, and pull requests. Use the deployment checklist before opening a hosted instance to users.
This project is licensed under the MIT License.
Google sign-in now supports public access with 4 lifetime analysis pages, a 400-page monthly application budget, 2-page/4-MiB files, 10 documents per account and 30-day original retention. See deployment and operator instructions.
Two persisted profiles are available: User (public trial limits) and Admin (no Wida quotas). The configured administrator is assigned on verified Google sign-in; see profile configuration and migrations.