Invoice Pro v1.0

AI-powered invoice extraction and financial management platform

Complete SaaS solution with Next.js 16 frontend, Go backend microservices, document extraction, and intelligent data processing.

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Go 1.25+
• Node.js 18+
• PostgreSQL 15+
• Redis 7+

Installation

# Clone repository
git clone https://github.com/yourusername/invoice-pro.git
cd invoice-pro

# Install dependencies
./deploy.sh install

# Start development
docker-compose up -d

Access Points

🏗️ Architecture

System Overview

┌─────────────────────────────────────────────────┐
│              Frontend (Next.js 16)              │
│  • App Router, TypeScript, Tailwind CSS        │
│  • Connect-RPC gRPC client                     │
│  • React Query for state management            │
└────────────────┬────────────────────────────────┘
                 │ HTTP/gRPC-Web
                 ▼
┌─────────────────────────────────────────────────┐
│         Backend Services (Go)                   │
│  ┌──────────────────────────────────────────┐  │
│  │  Rate Limiter (Redis)                    │  │
│  └──────────────┬───────────────────────────┘  │
│                 ▼                                │
│  ┌──────────────────────────────────────────┐  │
│  │  Authentication (JWT)                    │  │
│  └──────────────┬───────────────────────────┘  │
│                 ▼                                │
│  ┌──────────────────────────────────────────┐  │
│  │  Business Logic Handlers                 │  │
│  │  • Accounting Service                    │  │
│  │  • Import Service                        │  │
│  │  • Integration Service                   │  │
│  │  • AI Agent Service                      │  │
│  └──────────────────────────────────────────┘  │
└────────────────┬────────────────────────────────┘
                 │
    ┌────────────┼────────────┐
    ▼            ▼            ▼
┌─────────┐  ┌────────┐  ┌──────────┐
│PostgreSQL│  │ Redis  │  │ AI APIs  │
│(Primary) │  │(Cache) │  │(OpenAI)  │
└─────────┘  └────────┘  └──────────┘

📦 Data Import System Complete

Overview

Universal CSV/Excel import with AI-powered column mapping. Supports any provider (Paystack, Stripe, Flutterwave, Square) with automatic field detection and transformation.

Key Features

• ✅ CSV & Excel (.xlsx, .xls) file upload
• ✅ AI-powered column mapping with 70-95% accuracy
• ✅ Template matching for instant imports (100% confidence, zero AI cost)
• ✅ Pre-seeded templates for Stripe and Paystack
• ✅ Value transformations (divide_by, currency conversion, value_mapping)
• ✅ Duplicate detection via ExternalTransactionSource
• ✅ Multi-step wizard UI with progress tracking
• ✅ Integration-aware imports (standalone + from integrations page)

Import Strategy

Database Schema

import_sessions
  - id, tenant_id, filename, status
  - total_rows, processed_rows, error_rows
  - integration_id, provider, template_id
  
import_field_mappings
  - session_id, source_column, target_entity, target_field
  - mapping_strategy (template/ai/rules)
  - confidence_score, transformations (JSONB)
  
import_errors
  - session_id, row_number, field_name, error_message
  
import_templates
  - name, description, provider
  - column_mappings (JSONB), is_public
  
mapping_cache
  - cache_key (hash of columns), mapping_result (JSONB)
  - hit_count, expires_at

API Endpoints (gRPC)

• UploadImportFile - Upload CSV/Excel, start analysis
• GetImportMappings - Get AI/template mappings
• UpdateFieldMapping - Manual mapping adjustment
• ConfirmMappings - Lock mappings, optionally save template
• ExecuteImport - Process file, create payments/entries
• GetImportSession - Session status & progress
• ListImportSessions - All imports with pagination
• GetImportErrors - Row-level error details
• ListImportTemplates - Available templates
• CreateImportTemplate - Save mappings for reuse
• DeleteImportTemplate - Remove template
• CancelImport - Abort running import

Frontend Components

frontend/src/
├── app/dashboard/data-imports/
│   ├── page.tsx                 (list all imports)
│   ├── new/page.tsx             (import wizard)
│   ├── [id]/page.tsx            (import details)
│   └── templates/page.tsx       (manage templates)
├── components/data-imports/
│   ├── import-wizard.tsx        (multi-step wizard)
│   ├── upload-step.tsx
│   ├── review-step.tsx
│   └── execute-step.tsx
├── hooks/
│   └── use-imports.ts           (8 React hooks)
└── lib/api/
    └── imports.ts               (ImportsAPI client)

Usage Example

// Upload file
const session = await ImportsAPI.uploadFile({
  tenantId: 'uuid',
  file: csvFile,
  integrationId: 'uuid', // optional
  provider: 'stripe',    // optional
  templateId: 'uuid',    // optional (instant import)
})

// Get mappings (AI or template)
const { mappings } = await ImportsAPI.getMappings(tenantId, sessionId)

// Adjust if needed
await ImportsAPI.updateMapping({
  tenantId,
  sessionId,
  mappingId: 'uuid',
  targetField: 'amount',
  isUserConfirmed: true
})

// Execute import
await ImportsAPI.executeImport(tenantId, sessionId)

⚡ Workflow Automation Phase 6 Complete

Overview

Visual workflow builder with scheduled execution, AI-powered automation, and seamless integration management. Build complex business processes with drag-and-drop nodes.

Key Features

• ✅ Visual drag-and-drop workflow builder (V2)
• ✅ Template variable substitution with {{variable}} syntax
• ✅ Loop node for array iteration with context setting
• ✅ Condition node with 12 comparison operators
• ✅ Transform node for data mapping and manipulation
• ✅ Scheduled execution with cron-based scheduler
• ✅ Real Paystack API integration with transaction sync
• ✅ Integration-aware workflow builder with validation
• ✅ 11 node executors with comprehensive functionality

Workflow Architecture

┌──────────────────────────────────────────────────┐
│        Workflow Builder (Frontend V2)            │
│  • Drag-and-drop canvas with zoom/pan           │
│  • Node palette (triggers, actions, logic)       │
│  • Configuration sidebar                         │
│  • Integration validation before save            │
└────────────────┬─────────────────────────────────┘
                 │ HTTP POST /api/workflows
                 ▼
┌──────────────────────────────────────────────────┐
│      Workflow API Route (Next.js)                │
│  • Validates required integrations               │
│  • Returns 400 if integration missing            │
│  • Saves workflow definition to backend          │
└────────────────┬─────────────────────────────────┘
                 │ gRPC createWorkflow
                 ▼
┌──────────────────────────────────────────────────┐
│       Backend Workflow Services (Go)             │
│  ┌────────────────────────────────────────────┐ │
│  │  Workflow Scheduler (Cron)                 │ │
│  │  • Polls for scheduled workflows           │ │
│  │  • Triggers execution at intervals         │ │
│  └────────────┬───────────────────────────────┘ │
│               ▼                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  Workflow Runner (Graph Executor)          │ │
│  │  • Resolves {{template}} variables         │ │
│  │  • Executes nodes in dependency order      │ │
│  │  • Manages execution context               │ │
│  └────────────┬───────────────────────────────┘ │
│               ▼                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  Node Executors (11 types)                │ │
│  │  • Triggers: paystack_sync                 │ │
│  │  • Actions: create_payment, create_contact │ │
│  │  • Logic: condition, loop, transform       │ │
│  └────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

Node Executors

Template Variable System

Use {{variable}} syntax to reference data from previous nodes. Supports dot notation for nested fields.

// Template syntax examples
{{current_transaction.amount}}       // Access nested field
{{loop_item.customer.email}}         // Access from loop context
{{paystack_transactions[0].status}}  // Array indexing

// Context variables
{{loop_item}}      // Current item in loop
{{loop_index}}     // Current iteration index (0-based)
{{loop_total}}     // Total items in array
{{loop_is_first}}  // Boolean: first iteration
{{loop_is_last}}   // Boolean: last iteration

Condition Operators

Integration-Aware Workflow Builder

When creating workflows that require integrations (Paystack, Stripe, etc.), the system automatically validates that integrations are connected before saving.

User Flow

1. User drags Paystack Scheduled Sync node onto canvas
2. Node configuration shows alert: "⚠️ Integration Required - Connect Paystack Integration →"
3. User configures polling interval and transaction filter
4. User clicks Save Workflow
5. Backend validates that Paystack integration exists and is connected
6. If missing: Returns 400 error with provider name
7. Frontend shows alert: "Please connect Paystack integration before saving"
8. User clicks link → Redirects to integrations page
9. User connects Paystack with API key
10. Returns to workflow builder and saves successfully ✅

Backend Validation

// API Route: /api/workflows (POST)

// Extract integration nodes
const integrationNodes = nodes.filter(node => 
  node.nodeType === 'paystack_scheduled_sync' || 
  node.nodeType === 'stripe_scheduled_sync'
)

// Check each integration
for (const node of integrationNodes) {
  const provider = node.nodeType.replace('_scheduled_sync', '')
  
  const integrations = await accountingClient.listIntegrations({})
  const hasIntegration = integrations.some(
    int => int.provider === provider && int.status === 'connected'
  )
  
  if (!hasIntegration) {
    return NextResponse.json({
      error: 'Missing required integrations',
      missingIntegrations: [{ provider }],
      message: `Please connect ${provider} before saving`
    }, { status: 400 })
  }
}

Frontend Node Configuration

// Paystack Sync Node Config UI

{selectedNode.nodeType === "paystack_scheduled_sync" && (
  <>
    <div className="bg-blue-50 border border-blue-200 rounded p-3">
      <AlertCircle className="text-blue-600" />
      <span className="font-semibold">Integration Required</span>
      <p>This workflow requires a connected Paystack integration.</p>
      <a href="/integrations">Connect Paystack Integration →</a>
    </div>
    
    <select>
      <option value="15">Every 15 minutes</option>
      <option value="60">Every hour</option>
      <option value="1440">Daily (recommended)</option>
    </select>
  </>
)}

Example Workflow: Auto-Import Paystack Transactions

{
  "name": "Auto-import Paystack Transactions",
  "nodes": [
    {
      "id": "node_1",
      "nodeType": "paystack_scheduled_sync",
      "config": {
        "polling_interval": "1440",
        "from_date": "{{today - 7 days}}",
        "to_date": "{{today}}",
        "transaction_filter": "success_only"
      }
    },
    {
      "id": "node_2",
      "nodeType": "loop",
      "config": {
        "array_path": "paystack_transactions.transactions"
      }
    },
    {
      "id": "node_3",
      "nodeType": "condition",
      "config": {
        "field": "{{loop_item.amount}}",
        "operator": "greater_than",
        "value": 10000
      }
    },
    {
      "id": "node_4",
      "nodeType": "create_payment",
      "config": {
        "amount": "{{loop_item.amount}}",
        "reference": "{{loop_item.reference}}",
        "customer_email": "{{loop_item.customer.email}}",
        "payment_type": "received",
        "payment_method": "card"
      }
    },
    {
      "id": "node_5",
      "nodeType": "create_journal",
      "config": {
        "description": "Payment received: {{loop_item.reference}}",
        "lines": [
          {
            "account_code": "1010",
            "debit": "{{loop_item.amount}}"
          },
          {
            "account_code": "4010",
            "credit": "{{loop_item.amount}}"
          }
        ]
      }
    }
  ],
  "connections": [
    { "sourceId": "node_1", "targetId": "node_2" },
    { "sourceId": "node_2", "targetId": "node_3" },
    { "sourceId": "node_3", "targetId": "node_4", "type": "true_branch" },
    { "sourceId": "node_4", "targetId": "node_5" }
  ]
}

Workflow Execution Flow

1. Scheduler triggers workflow (daily at midnight)
2. Paystack Sync Node fetches last 7 days of transactions via API
3. Loop Node iterates over each transaction, sets {{loop_item}}
4. Condition Node checks if amount > ₦10,000
5. Create Payment Node creates payment record with resolved values
6. Create Journal Node generates double-entry journal entry
7. Workflow completes, logs execution summary

Paystack API Integration

Real HTTP integration to api.paystack.co/transaction with pagination, date filtering, and Bearer authentication.

// Paystack Sync Executor (Go)

func (e *PaystackSyncExecutor) Execute(ctx context.Context, ...) {
  // 1. Get integration credentials
  integration := getIntegration(tenantID, "paystack")
  
  // 2. Fetch transactions from Paystack
  transactions := fetchPaystackTransactions(
    integration.SecretKey,
    config.FromDate,
    config.ToDate,
    100 // perPage
  )
  
  // 3. Transform API response
  for _, txn := range transactions {
    amount := txn.Amount / 100 // kobo to naira
    processedTxns = append(processedTxns, {
      "amount": amount,
      "reference": txn.Reference,
      "status": txn.Status,
      "customer": {
        "email": txn.Customer.Email,
        "name": txn.Customer.FirstName + " " + txn.Customer.LastName
      }
    })
  }
  
  // 4. Store in execution context
  return map[string]interface{}{
    "paystack_transactions": {
      "transactions": processedTxns,
      "total": len(processedTxns)
    }
  }
}

Performance

• Template Resolution: ~50µs per variable
• Node Execution: ~200µs per node (avg)
• Paystack API: ~1.5s per 100 transactions
• Loop Iteration: ~100µs per item
• Total Workflow: ~5s for 1000 transactions

Files

🔒 Rate Limiting Complete

Overview

Multi-tier token bucket rate limiting with Redis. Protects API from abuse with automatic retry and user-friendly feedback.

Architecture

• ✅ Global limiting (10k req/min)
• ✅ Tenant limiting (1k req/min)
• ✅ User limiting (200 req/min)
• ✅ Method-specific limits (AI: 100/min, uploads: 200/min, bulk: 50/min)
• ✅ Frontend: Automatic retry with exponential backoff
• ✅ Frontend: Toast notifications with countdown

Default Limits

Backend Implementation

// Go - Rate limiter with token bucket
rateLimiter := middleware.NewRateLimiter(redisClient, config)

// gRPC interceptor chain
grpcSrv := grpc.NewServer(
    grpc.ChainUnaryInterceptor(
        rateLimiter.Unary(),      // Rate limit FIRST
        authInterceptor.Unary(),  // Auth second
    ),
)

Frontend Integration

// Automatic retry on rate limit
import { withRateLimitRetry } from '@/lib/rate-limit-handler'

const result = await withRateLimitRetry(async () => {
  return await fetch('/api/endpoint')
})
// Retries 3x with backoff: 1s → 2s → 4s

// Toast notification
import { useRateLimitToast } from '@/components/ui/rate-limit-toast'

const { toast, showToast } = useRateLimitToast()
if (isRateLimited) {
  showToast("Rate limit reached, retrying in 3s...", 3)
}

Performance

• Latency: ~187µs per check
• Throughput: 100k+ checks/sec
• Memory: ~200 bytes per key
• Tests: 8/8 passing

🤖 AI Chatbot Enhanced

Overview

Natural language interface for financial queries. Powered by OpenAI with context-aware function calling.

Features

• ✅ Natural language queries ("Show me Q3 revenue")
• ✅ Context-aware responses with tenant data
• ✅ Function calling for database queries
• ✅ Conversation history with session management
• ✅ Real-time streaming responses

Available Functions

Usage

// Frontend - Chat with AI
import { accountingClientBrowser } from '@/lib/connect-rpc-browser'

const stream = accountingClientBrowser.chatWithAI({
  tenantId: 'uuid',
  sessionId: 'uuid',
  userMessage: 'What was my revenue last month?'
})

for await (const response of stream) {
  console.log(response.assistantMessage)
}

🔌 Integrations Active

Supported Providers

Integration Architecture

┌─────────────────────────────────────────┐
│     Integration Manager                 │
├─────────────────────────────────────────┤
│                                         │
│  ┌──────────────┐   ┌──────────────┐  │
│  │  API Sync    │   │  CSV Import  │  │
│  │  (Paystack)  │   │  (All)       │  │
│  └──────┬───────┘   └──────┬───────┘  │
│         │                  │           │
│         ▼                  ▼           │
│  ┌─────────────────────────────────┐  │
│  │  ExternalTransactionSource      │  │
│  │  (Deduplication & Linking)      │  │
│  └─────────────────────────────────┘  │
│         │                               │
│         ▼                               │
│  ┌─────────────────────────────────┐  │
│  │  Payment & Journal Entry        │  │
│  └─────────────────────────────────┘  │
└─────────────────────────────────────────┘

Dual Entry Points

• From Integrations Page: Click "Import Data" on connected integration → Pre-fills integrationId
• Standalone: Data Imports → New Import → Provider selection dropdown

📊 Pitch Deck Generation Active

Overview

AI-generated investor pitch decks with live financial metrics. Connect data sources, answer questions, get presentation-ready slides.

Features

• ✅ AI-powered slide generation from financial data
• ✅ Real-time metrics (MRR, burn rate, runway)
• ✅ Customizable templates and branding
• ✅ Export to PDF/PowerPoint
• ✅ Version history and collaboration

Data Sources

• Dashboard stats (revenue, expenses, profit)
• Transaction history and trends
• MRR and subscription metrics
• User-provided business context
• Uploaded presentation assets (logos, charts)

⚙️ Backend Services

Service Architecture

backend/
├── cmd/
│   └── server/
│       └── main.go              (gRPC server, interceptors)
├── internal/
│   ├── accountingserver/        (20+ gRPC handlers)
│   │   ├── accounts.go
│   │   ├── payments.go
│   │   ├── journalentries.go
│   │   ├── reconciliation.go
│   │   ├── ai_agent.go
│   │   └── ...
│   ├── services/                (Business logic)
│   │   ├── import_parser_service.go
│   │   ├── import_mapper_service.go
│   │   ├── import_service.go
│   │   ├── ai_agent_service.go
│   │   └── ...
│   ├── middleware/
│   │   ├── ratelimit.go         (Rate limiting)
│   │   └── auth.go              (JWT validation)
│   ├── database/
│   │   └── database.go          (GORM setup)
│   └── models/
│       └── models.go            (50+ database models)
└── proto/
    └── accounting.proto         (gRPC definitions)

Key Services

Database Models (50+)

• Tenant, User, TenantMembership
• Account, Transaction, Payment
• JournalEntry, JournalLine
• ImportSession, ImportFieldMapping, ImportError, ImportTemplate
• Integration, ExternalTransactionSource
• ExpensePolicy, ExpenseClaim, ExpenseApproval
• AIQueryHistory, Subscription, PitchData

🎨 Frontend App

Tech Stack

• Framework: Next.js 16 (App Router)
• Language: TypeScript
• Styling: Tailwind CSS v4
• State: React Query (@tanstack/react-query)
• API: Connect-RPC (gRPC-Web)
• Forms: React Hook Form + Zod
• Charts: Recharts

Structure

frontend/src/
├── app/
│   ├── (auth)/
│   │   ├── login/page.tsx
│   │   └── register/page.tsx
│   └── dashboard/
│       ├── page.tsx              (dashboard)
│       ├── payments/
│       ├── journal-entries/
│       ├── accounts/
│       ├── data-imports/
│       ├── integrations/
│       └── settings/
├── components/
│   ├── ui/                       (shadcn components)
│   ├── dashboard/
│   ├── data-imports/
│   └── pitch-deck/
├── lib/
│   ├── connect-rpc-browser.ts   (gRPC client)
│   ├── rate-limit-handler.ts
│   └── api/
│       └── imports.ts
├── hooks/
│   └── use-imports.ts           (React hooks)
└── gen/
    ├── accounting_pb.ts         (Protobuf messages)
    └── accounting_connect.ts    (gRPC service)

🗄️ Database Schema

Core Tables

-- Tenants & Users
tenants (id, name, base_currency, created_at)
users (id, email, password_hash, created_at)
tenant_memberships (tenant_id, user_id, role)

-- Accounting
accounts (id, tenant_id, name, type, code, parent_id)
transactions (id, tenant_id, amount, date, type, status)
payments (id, tenant_id, amount, date, type, payment_method)
journal_entries (id, tenant_id, date, description, status)
journal_lines (entry_id, account_id, debit, credit)

-- Data Imports
import_sessions (id, tenant_id, filename, status, total_rows)
import_field_mappings (id, session_id, source_column, target_field)
import_errors (id, session_id, row_number, error_message)
import_templates (id, name, provider, column_mappings)
mapping_cache (cache_key, mapping_result, expires_at)

-- Integrations
integrations (id, tenant_id, provider, status, credentials)
external_transaction_sources (integration_id, external_id, transaction_id)

-- AI & Analytics
ai_query_history (id, tenant_id, user_id, query, response)
subscriptions (id, tenant_id, plan, mrr, status)
pitch_data (tenant_id, data_type, content)

🚀 Production Deployment

Deployment Script

# Install dependencies
./deploy.sh install

# Deploy to production
./deploy.sh deploy

# Setup SSL certificate
./deploy.sh ssl yourdomain.com

# Status check
./deploy.sh status

Docker Compose Services

Environment Variables

# Backend (.env)
DATABASE_URL=postgres://user:pass@postgres:5432/invoicepro
REDIS_URL=redis://redis:6379
JWT_SECRET=your-secret-key
OPENAI_API_KEY=sk-...
PAYSTACK_SECRET_KEY=sk_...

# Frontend (.env.local)
NEXT_PUBLIC_GRPC_WEB_URL=http://localhost:8080
NEXT_PUBLIC_API_URL=http://localhost:3000/api

Resource Limits (Optimized for $6-24/mo droplets)

📊 Monitoring

Health Checks

# Check all services
docker-compose ps

# View logs
docker-compose logs -f backend
docker-compose logs -f frontend

# Database connection
docker-compose exec postgres psql -U postgres -d invoicepro

# Redis status
docker-compose exec redis redis-cli INFO

Key Metrics

• Rate Limiting: Monitor ResourceExhausted errors (code 8)
• Import System: Track import_sessions.status distribution
• API Performance: gRPC response times < 100ms average
• Database: Connection pool usage, slow queries
• Redis: Memory usage, eviction rate

Invoice Pro Documentation | Complete Implementation Guide | 2025
For detailed rate limiting documentation, see rate-limiting.html