BillSync

A supplier purchase bill describes stock that has arrived: who supplied it, which products it contains, and the line items an inventory system needs. But a bill is a document, not data. Before it can change inventory, the information in it has to be read, structured, and checked.

AI extraction can turn a document into structured fields, but what it produces is an interpretation, not a guarantee. A misread product or quantity that flows straight into stock levels becomes an inventory error, and every later decision builds on it. For data a business relies on, an unverified interpretation is not a sufficient source of truth.

The initial domain context is inventory for independent medical stores in India. The architecture is deliberately built around general document and inventory workflows rather than that one domain, so the same model can extend to other industries.

BillSync treats three things that are easy to conflate as separate, each with its own responsibility.

None of them silently stands in for another. The document stays available as evidence. The extraction records what the system proposed. Only verified data is treated as authoritative and allowed to change inventory. Keeping the stages apart is what makes it possible to answer, later, where a number came from and who confirmed it.

A bill moves through seven stages, from upload to history.

The diagram shows the development architecture BillSync is being built around. It describes the structure and direction of the system, not a production deployment.

The request path ends when the upload is accepted. Everything after the message broker happens in the background, on workers. Human verification sits between extraction and business data as an explicit step, not an optional one. PostgreSQL holds both the extraction history and the verified business state, in separate tables, so one never overwrites the other.

Reading and extracting a document is potentially longer work than a user-facing request should wait on. BillSync separates the two.

The upload side acts as a producer: it accepts the document and publishes the processing work to a message broker. A worker consumes that work, processes the document, and persists the extraction result. RabbitMQ is the current message broker.

Bill processing has lifecycle status handling around it, so the rest of the system can tell where a bill is in the flow without depending on the processing call itself.

AI output is treated as an intermediate representation: the starting point for review, never an automatic write to business data. This section describes the structure of the pipeline, not a specific model or provider.

Three tables carry the pipeline's history:

• extraction_attempts tracks each extraction attempt separately from the bill it belongs to, so a bill's processing history is retained rather than overwritten.
• extraction_snapshots preserve the structured data an extraction produced, as it was produced.
• corrections represent changes a person makes during review, kept distinct from the machine output they change.

PostgreSQL is the database foundation, accessed through Drizzle ORM. The schema has eleven tables in five groups.

• Business and identity

  businesses

  Tenants: each business on the platform.

  users

  People who use the system.

• Document

  bills

  Uploaded supplier purchase bills.

  bill_items

  Line items that belong to a bill.

• Extraction

  extraction_attempts

  Each attempt to extract a bill.

  extraction_snapshots

  Structured data an extraction produced.

  corrections

  Human changes made during review.

• Inventory

  products

  Products the business stocks.

  batches

  Batches of a product.

  inventory_movements

  History of changes to inventory.

• Audit

  audit_events

  Important events retained as history.

Conceptually, the groups follow the workflow. Businesses and users define who owns and acts on the data. A bill owns its line items and its extraction history, and corrections record what a person changed in that history. Verified data flows into products and batches, and changes to stock are recorded as inventory movements. Audit events cut across the groups.

BillSync is designed as a multi-tenant SaaS. Each business is a separate tenant.

• ADMIN has administrative rights within its own business only, including managing that business's STAFF users.
• STAFF users belong to one business.
• Business users are not given access to any other business.
• SUPER_ADMIN belongs to the platform operator, not to a business. The architecture provides for platform-level, cross-business insights at that layer.

Tenancy is part of the foundation rather than added later: businesses and users are core tables, so tenant boundaries are expressed in the data model from the start.

BillSync does not overwrite an extraction with its corrected result. Each stage is kept as its own record.

The system separates evidence, machine interpretation, human correction, and business state.

Preserving each stage is designed to give the system properties that a single overwritten record cannot:

• Traceability. Business data can be followed back through corrections and extractions to the original bill.
• Distinguishability. What the machine proposed and what a person changed remain separate facts.
• Retained processing history. Extraction attempts are tracked separately, so earlier attempts are not lost.
• Inventory as history. Inventory movements record how stock changed, not only where it stands now.

The database foundation is implemented and verified in the BillSync project.

Database foundation

• PostgreSQL with Drizzle ORM
• Eleven core tables across identity, documents, extraction, inventory, and audit
• A migration system
• Relationships between tables defined and covered by tests
• Automated tests for the database package

Local development infrastructure

Docker Compose runs the services the architecture depends on:

• PostgreSQL 16
• RabbitMQ 3.13
• Redis 7
• MinIO

This is the local development setup, not a production environment.

The design decisions the architecture is built on, and the reasoning behind each.

1. 01

   AI extraction is not authoritative business data.

   WhyExtraction is an interpretation of a document. Treating it as an intermediate result keeps unverified output out of inventory state.

2. 02

   Human verification comes before business state is trusted.

   WhyA person confirms or corrects the extraction, so authoritative data always has a human decision behind it.

3. 03

   Processing is asynchronous.

   WhyThe upload request does not wait on potentially longer document processing, which workers handle independently of the user-facing action.

4. 04

   Extraction history is retained separately.

   WhyAttempts, snapshots, and corrections are separate records, so it stays clear what the system produced and what a person changed.

5. 05

   Multi-tenancy is part of the architecture, not an afterthought.

   WhyBusinesses and users are foundation tables, so tenant boundaries are part of the data model from the start.

6. 06

   Audit and history are modeled explicitly.

   WhyAudit events and inventory movements are tables of their own, so important history is part of the data model itself.

7. 07

   Document processing is separated from inventory state.

   WhyDocument and extraction tables are distinct from products, batches, and movements, and inventory is designed to change only through verified data.

BillSync is currently being developed. The database foundation is implemented and verified; the application workflow built on top of it is not complete.

• Established

  • Database foundation
  • Core domain model
  • Multi-tenant data model direction
  • Document and extraction data model
  • Local development infrastructure

• Current direction

  • Asynchronous processing through a message broker and workers
  • Human verification before data becomes authoritative
  • Tenant-scoped business roles and a platform layer
  • Redis as part of the infrastructure

• Planned next

  • Complete the end-to-end processing flow
  • Complete the verification workflow
  • Connect extraction to verified inventory updates
  • Expand operational workflows
  • Continue hardening reliability and deployment

The next phase is to connect the database foundation to the complete document-processing and verification workflow, then harden the system around reliability, auditability, and operational inventory behavior.