Dunlin MVP

Client Intake → OCR → Reconcile → Tab-to-Categorize → QBO Export

A minimal working MVP for automated client document processing, transaction extraction, reconciliation, and categorization with keyboard-first UX.

🏗️ Architecture

This is a monorepo with separate backend and frontend applications:

/
├── backend/          # Node.js + Fastify + TypeScript + PostgreSQL
├── frontend/         # React + Tailwind CSS + Keyboard-first UX
├── shared/           # Common types and constants
├── instructions.md   # Detailed requirements and specs
├── setup-backend.sh  # Backend setup script
├── setup-frontend.sh # Frontend setup script
└── README.md         # This file

🚀 Quick Start

Full MVP Setup (5 minutes)

# One-command setup for everything
npm run setup:all

# Or separately:
npm run setup:backend   # Sets up backend with database
npm run setup:frontend  # Sets up frontend

Start Development Servers

# Start both frontend and backend together
npm run dev

# Or separately:
npm run dev:backend   # Backend at http://localhost:3001
npm run dev:frontend  # Frontend at http://localhost:3000

URLs:

• Frontend (React): http://localhost:3000
• Backend API: http://localhost:3001
• API Docs: http://localhost:3001/health

📋 Features Implemented

✅ Backend (Complete)

• File Upload: POST /api/upload - Multipart file upload with metadata
• OCR Extraction: GET /api/extract/:file_id - Transaction extraction from documents
• Reconciliation: POST /api/reconcile - Match extracted transactions to ledger
• Category Suggestions: GET /api/suggest - AI-powered categorization based on history
• CSV Export: POST /api/export - Generate downloadable transaction reports
• Database Schema: Complete PostgreSQL schema with migrations and seed data
• Mock OCR: Sample transaction data for testing (easily replaceable with real OCR)

✅ Frontend (Complete)

• Upload UI: Drag & drop file upload with progress feedback
• Reconciliation Studio: List of extracted transactions with match status
• Keyboard-First UX: Tab to accept, ↓ for alternatives, / for search, Ctrl+B for bulk apply
• Evidence Panel: OCR text, transaction details, and confidence scores
• Category Suggestions: Real-time suggestions with confidence indicators
• Export Functionality: Select and download CSV with categorized transactions
• Responsive Design: Clean, modern UI with Tailwind CSS

🎯 MVP Demo Flow

GUI Demo (Recommended - 90 seconds)

1. Visit http://localhost:3000
2. Upload any file (PDF, image, or text) via drag & drop
3. View extracted transactions with OCR text and match status
4. Click on a transaction to focus it and see category suggestions
5. Press Tab to accept the top suggestion, ↓ to cycle alternatives
6. Select multiple transactions using checkboxes
7. Click "Export Selected" to download CSV

API Demo (Technical)

# 1. Upload Document
curl -X POST -F "[email protected]" -F "firm_id=550e8400-e29b-41d4-a716-446655440000" \
     http://localhost:3001/api/upload

# 2. Extract Transactions
curl "http://localhost:3001/api/extract/{file_id}"

# 3. Reconcile with Ledger
curl -X POST -H "Content-Type: application/json" \
     -d '{"firm_id":"550e8400-e29b-41d4-a716-446655440000","extracted_transaction_ids":[...]}' \
     http://localhost:3001/api/reconcile

# 4. Get Category Suggestions
curl "http://localhost:3001/api/suggest?firm_id=550e8400-e29b-41d4-a716-446655440000&vendor=Zoom"

# 5. Export to CSV
curl -X POST -H "Content-Type: application/json" \
     -d '{"firm_id":"550e8400-e29b-41d4-a716-446655440000","transaction_ids":[...],"format":"csv"}' \
     http://localhost:3001/api/export

🗄️ Database Schema

Core Tables

• firms - Accounting firms
• files - Uploaded document files
• extracted_transactions - OCR-extracted transaction data
• ledger_transactions - Existing QuickBooks/Xero ledger data
• category_history - Machine learning categorization history
• matches - Reconciliation match results
• exports - Generated export files

Sample Data Included

• Demo accounting firm with sample ledger transactions
• Realistic vendor data (Zoom, Adobe, AWS, Office Depot, etc.)
• Pre-populated category history for intelligent suggestions

🔧 Development

Backend Development

cd backend
npm run dev          # Start with hot reload
npm test            # Run tests
npm run db:migrate  # Run new migrations
npm run db:seed     # Load sample data

API Testing with Postman

Import the following collection or test manually:

Health Check

GET http://localhost:3001/health

Upload File

POST http://localhost:3001/api/upload
Content-Type: multipart/form-data
Body: file + firm_id

Extract Transactions

GET http://localhost:3001/api/extract/{file_id}

🚢 Deployment

Backend (Railway, Render, etc.)

npm run build
npm start

Database

• Production: Use managed PostgreSQL (Supabase, Railway, etc.)
• Local dev: Docker PostgreSQL

Environment Variables

DB_HOST=your-db-host
DB_PORT=5432
DB_NAME=dunlin_prod
DB_USER=your-db-user
DB_PASSWORD=your-db-password
PORT=3001
OCR_MOCK_MODE=false  # Enable real OCR in production

✅ Acceptance Criteria - All Met

• ✅ File Upload: Can upload files and see extraction results
• ✅ OCR Processing: Mock OCR returns realistic transaction data (easily replaceable)
• ✅ Reconciliation: Transactions match against seed ledger with confidence scoring
• ✅ Tab-to-Categorize: Tab accepts suggestions, ↓ cycles alternatives, keyboard-first UX
• ✅ CSV Export: Selected transactions export to properly formatted CSV
• ✅ Evidence Panel: OCR text, transaction details, and confidence indicators
• ✅ API Contracts: All 5 endpoints implemented and tested
• ✅ Database Schema: Complete with migrations and sample data
• ✅ Demo Ready: 90-second demo flow working end-to-end

🔮 Roadmap

Phase 1 (✅ Complete): MVP Core

• ✅ File upload and storage
• ✅ Mock OCR with realistic sample data
• ✅ Transaction reconciliation logic
• ✅ Category suggestion engine
• ✅ CSV export functionality
• ✅ React frontend with keyboard-first UX
• ✅ Complete integration and testing

Phase 2: Production OCR

• Google Vision API integration
• AWS Textract integration
• Tesseract.js fallback
• OCR confidence scoring and error handling

Phase 3: Advanced Features

• QBO/Xero writeback integration
• Advanced reconciliation rules (running balance checks)
• Bulk operations and workflow management
• Multi-firm support and user authentication

📚 Documentation

• Detailed Requirements - Complete MVP specifications
• Backend API Docs - API endpoints and database schema
• Frontend Docs - React component documentation

🤝 Contributing

1. Backend-first development approach
2. Mock data for rapid iteration
3. Real OCR integration after core flows are working
4. Keyboard-first UX principles

📄 License

This project is part of the Dunlin MVP development sprint.