WunderLedger

WunderLedger is an AI-assisted invoice and receipt categorisation SaaS platform designed for SMEs, accountants, and finance teams. The MVP is a web-first, multi-tenant product with Dropbox-first ingestion, OCR-driven extraction, rules-first categorisation, AI fallback, manual review, monthly summaries, and Excel export.

This repository is structured as a modular monorepo so that connectors, OCR providers, export targets, country presets, and runtime services can evolve independently without breaking the core product.

1. Product objective

WunderLedger aims to reduce the operational burden of invoice and receipt handling by providing:

• secure document ingestion from Dropbox and manual upload
• OCR and structured field extraction
• rules-first categorisation with controlled AI fallback
• human review queue for low-confidence or ambiguous items
• transaction and monthly summary generation
• accountant-friendly Excel export
• internal admin and operational visibility
• country-aware configuration, with Hong Kong as the first production preset

2. Architecture principles

The repository and delivery plan are based on the following non-negotiable principles:

1. Web MVP first

   • The first live release is a web application.
   • Mobile capture is deferred to Phase 1.5.

2. Multi-tenant by design

   • Tenant separation is enforced at the database layer with Postgres Row Level Security.
   • Workspace membership and role checks are also enforced in the application layer.

3. Rules-first, AI-second

   • Deterministic rules are used first for supplier, keyword, memory, and category assignment.
   • AI fallback is only invoked when rules cannot produce an acceptable result.
   • AI must be constrained to configured active categories and never invent unsupported categories.

4. Asynchronous processing

   • OCR, sync, exports, retries, and recalculation are handled in background workers.
   • User-facing API paths should remain responsive and not block on long-running jobs.

5. Configuration over hardcoding

   • Country defaults, categories, parser hints, export rules, and tax labels are stored as data or configuration.
   • Hong Kong is the first active country profile, but the platform must be extensible to other countries.

6. Replaceable providers

   • Dropbox is the first ingestion connector.
   • Google Document AI is the first OCR provider.
   • Excel is the first export target.
   • All of these are abstracted behind interfaces to support later replacement or expansion.

7. TDD and regression discipline

   • Domain logic is built with test-driven development where practical.
   • Every bug fix requires a regression test.
   • RLS policies, integration boundaries, and exports must all be test-covered.

3. Recommended technical stack

Frontend

• Next.js App Router
• TypeScript
• Tailwind CSS
• shadcn/ui
• TanStack Query
• React Hook Form
• Zod

Backend

• Node.js LTS
• Fastify for API and worker services
• OpenAPI for service contract documentation

Data and auth

• Supabase Auth
• Supabase Postgres
• Row Level Security
• SQL-first migrations

Document processing

• Google Document AI as the first OCR and invoice/receipt extraction provider

Background processing

• Google Cloud Run
• Google Cloud Tasks
• Google Cloud Scheduler
• Google Secret Manager
• Google Cloud Logging and Monitoring

Exports

• ExcelJS or SheetJS for .xlsx generation
• Google Sheets export in Phase 1.5

Testing

• Vitest
• Playwright
• Supertest
• Testcontainers where needed for integration parity

4. Recommended deployment model

Primary runtime

• Google Cloud is the primary runtime platform.

Database

• Supabase Postgres is the primary system-of-record database.

Source control and collaboration

• GitHub is the source control system and code review platform.

Replit

• Replit is not the source of truth.
• Replit may be used only for isolated prototyping or demos if needed.
• Backups must rely on GitHub, managed database backups, and infrastructure-as-code, not Replit.

5. Monorepo structure

wunderledger/
├─ apps/
│  ├─ web/
│  ├─ mobile/
│  ├─ admin/
│  ├─ api/
│  └─ worker/
├─ packages/
│  ├─ ui/
│  ├─ config/
│  ├─ types/
│  ├─ database/
│  ├─ auth/
│  ├─ tenancy/
│  ├─ country-profiles/
│  ├─ categories/
│  ├─ connectors/
│  │  ├─ core/
│  │  └─ dropbox/
│  ├─ document-core/
│  ├─ ocr/
│  │  ├─ core/
│  │  └─ google-document-ai/
│  ├─ categorisation/
│  │  ├─ rules-engine/
│  │  ├─ memory-engine/
│  │  └─ ai-fallback/
│  ├─ review/
│  ├─ transactions/
│  ├─ summaries/
│  ├─ exports/
│  │  ├─ excel/
│  │  └─ google-sheets/
│  ├─ jobs/
│  ├─ observability/
│  └─ testing/
├─ infra/
│  ├─ terraform/
│  │  ├─ environments/
│  │  │  ├─ dev/
│  │  │  ├─ staging/
│  │  │  └─ prod/
│  │  └─ modules/
│  │     ├─ cloud-run/
│  │     ├─ cloud-tasks/
│  │     ├─ secret-manager/
│  │     ├─ monitoring/
│  │     └─ scheduler/
│  ├─ supabase/
│  │  ├─ migrations/
│  │  ├─ seeds/
│  │  ├─ policies/
│  │  └─ functions/
│  └─ github/
│     └─ workflows/
├─ docs/
│  ├─ architecture/
│  ├─ product/
│  ├─ engineering/
│  └─ api/
├─ .github/
│  ├─ ISSUE_TEMPLATE/
│  ├─ PULL_REQUEST_TEMPLATE.md
│  └─ workflows/
├─ scripts/
├─ package.json
├─ turbo.json
├─ pnpm-workspace.yaml
├─ .env.example
└─ .gitignore

6. Application modules

Identity and tenancy

• user authentication
• workspace creation
• role-based access
• internal admin impersonation
• workspace-safe service access

Workspace configuration

• country profile
• currency/date/tax labels
• financial year configuration
• language defaults
• plan limits and feature flags

Source connectors

• Dropbox connector first
• later Google Drive, OneDrive, SharePoint, accounting APIs

Ingestion pipeline

• source file discovery
• deduplication
• normalisation
• queueing
• retry lifecycle

OCR and extraction

• provider abstraction
• raw OCR capture
• canonical field mapping
• confidence scoring
• extracted line items
• parser diagnostics

Categorisation engine

• supplier rules
• keyword rules
• memory-based assignment
• constrained AI fallback
• confidence and reasoning output

Review workflow

• review queue
• preview
• field editing
• approve / recategorise / duplicate / archive / reprocess

Transactions and summaries

• accounting-friendly transaction records
• monthly aggregation
• summary line generation
• reconciliation support

Export engine

• Excel export in MVP
• Google Sheets export in Phase 1.5
• export jobs and audit trail

Admin and ops

• workspace view
• job monitoring
• error centre
• audit logs
• usage metrics
• support tooling

7. Delivery phases

Phase 0 — Foundation

Target: 2 weeks

Scope:

• monorepo bootstrap
• CI/CD
• local developer tooling
• environment scaffolding
• Google Cloud and Supabase setup
• base schema
• test harness
• architecture documentation

Deliverables:

• repo structure
• initial README
• CI pipeline
• migrations
• baseline environment setup
• first ADR set

Phase 1 — Core web MVP

Target: 8 to 10 weeks

Scope:

• auth and tenancy
• workspace settings
• Hong Kong country profile
• categories
• manual upload
• Dropbox OAuth and sync
• OCR extraction
• rules-first categorisation
• AI fallback
• review queue
• transactions
• monthly summaries
• Excel export
• admin ops basics
• audit logging

Deliverables:

• web MVP deployed to staging
• complete review-to-export workflow
• admin visibility into jobs and errors
• UAT-ready demo pack

Phase 1.5 — Mobile and Google Sheets

Target: 4 to 6 weeks

Scope:

• Expo mobile app
• scan/capture flow
• upload and preview
• recent uploads
• Google Sheets export
• categorisation memory improvements
• duplicate handling improvements

Deliverables:

• mobile capture MVP
• Google Sheets export
• improved review ergonomics

Phase 2 — Expansion

Target: 6 to 10 weeks

Scope:

• more source connectors
• accounting platform integrations
• more country profiles
• billing enforcement
• expanded admin and support features

8. TDD strategy

The project follows practical TDD, not ceremonial TDD.

Unit tests

Used for:

• rule evaluation
• supplier mapping
• memory lookups
• summary calculations
• date and tax format resolution
• export formatting helpers

Integration tests

Used for:

• repository behaviour
• RLS policy behaviour
• API contract checks
• worker job handlers
• Dropbox adapter contract tests
• OCR mapping tests

End-to-end tests

Used for:

• auth and workspace creation
• manual upload to review queue
• review approval to transaction generation
• Dropbox sync flow
• export generation
• admin visibility

Regression policy

• Every production bug requires a failing test before the fix is merged.

9. Initial environments

• local
• dev
• staging
• prod

Local development expectations

• Supabase local or remote dev instance
• environment variables from .env.local
• seeded sample categories and country data
• mock Dropbox and OCR fixtures where practical

10. Security and compliance posture

The MVP should include:

• secure OAuth token storage
• encrypted secrets management
• workspace-safe database access
• audit logging for key state changes
• role-based access control
• document metadata tracking
• low-privilege service accounts
• staged environments
• no hardcoded secrets in repo

11. Initial repository deliverables

This repo-ready package includes:

• root README
• codebase bootstrap script
• .gitignore
• initial SQL schema
• milestone backlog
• GitHub labels and issues seed files
• ADR documents
• placeholder docs for architecture and engineering conventions

12. Immediate next actions

1. Run the bootstrap script in ~/WunderLedger/
2. Copy the generated files into the local repository root if needed
3. Review and adjust the README sections
4. Create the first milestone and issues in GitHub
5. Apply the Supabase migration
6. Begin Phase 0 implementation

13. Non-goals for MVP

Not in MVP unless later approved:

• full accounting platform integrations
• complex tax engine beyond country-configured defaults
• advanced AI explanation UI
• production billing engine
• multi-cloud deployment
• offline-first mobile support
• custom OCR provider marketplace

14. Repository conventions

Branching

• main for production-ready code
• develop optional if you prefer release train discipline
• short-lived feature branches for implementation

Commit style

Recommended:

• feat:
• fix:
• docs:
• test:
• refactor:
• chore:

PR requirements

• linked issue
• acceptance criteria satisfied
• tests added or updated
• no secret leakage
• docs updated where relevant

15. Ownership model

Suggested initial ownership:

• apps/web — frontend owner
• apps/api and apps/worker — backend owner
• packages/categorisation — domain owner
• packages/connectors/dropbox — integration owner
• infra/* — platform owner
• docs/* — shared ownership, tech lead approval

16. Status

This repository package is a starting framework, not a finished implementation. It is intentionally structured to support staged delivery, strict tenancy, modularity, and testability from the beginning.