Keepfig 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 Production Ready

Overview

Visual workflow builder with scheduled execution, AI-powered automation, and seamless integration management. Build complex business processes with drag-and-drop nodes that execute automatically on configurable intervals.

Key Features

• ✅ Visual drag-and-drop workflow builder (V2)
• ✅ Scheduled execution with cron-based automation
• ✅ Workflow activation/pause controls with status tracking
• ✅ 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
• ✅ Real Paystack API integration with transaction sync
• ✅ Integration-aware workflow builder with validation
• ✅ 11 node executors with comprehensive functionality
• ✅ Status-based execution control (draft/active/paused)

Workflow Architecture

┌──────────────────────────────────────────────────┐
│        Workflow Builder (Frontend V2)            │
│  • Drag-and-drop canvas with zoom/pan           │
│  • Node palette (triggers, actions, logic)       │
│  • Configuration sidebar                         │
│  • Integration validation before save            │
│  • Activate/Pause buttons with status badge      │
└────────────────┬─────────────────────────────────┘
                 │ Save → status: draft
                 │ Activate → /api/workflows/{id}/activate
                 ▼
┌──────────────────────────────────────────────────┐
│      Workflow API Routes (Next.js)               │
│  • POST /api/workflows - Create/update          │
│  • POST /activate - Set active + create schedule │
│  • POST /pause - Set paused + disable schedule   │
└────────────────┬─────────────────────────────────┘
                 │ gRPC: activateWorkflow, pauseWorkflow
                 ▼
┌──────────────────────────────────────────────────┐
│       Backend Workflow Services (Go)             │
│  ┌────────────────────────────────────────────┐ │
│  │  Workflow Scheduler (robfig/cron/v3)       │ │
│  │  • Auto-starts with app lifecycle          │ │
│  │  • Loads active schedules from DB          │ │
│  │  • Converts polling intervals to cron      │ │
│  │  • Executes workflows on schedule          │ │
│  │  • Checks workflow status before execution │ │
│  │  • Refresh loop every 5 minutes            │ │
│  └────────────┬───────────────────────────────┘ │
│               ▼                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  Workflow Runner (Graph Executor)          │ │
│  │  • Resolves {{template}} variables         │ │
│  │  • Executes nodes in dependency order      │ │
│  │  • Manages execution context               │ │
│  │  • Updates run counts and timestamps       │ │
│  └────────────┬───────────────────────────────┘ │
│               ▼                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  Node Executors (11 types)                │ │
│  │  • Triggers: paystack_scheduled_sync       │ │
│  │  • Actions: create_payment, create_contact │ │
│  │  • Logic: condition, loop, transform       │ │
│  └────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

Scheduled Execution System

Workflows can be activated to run automatically on configurable intervals. The scheduler uses cron expressions and tracks execution history.

Polling Intervals

Workflow Lifecycle

// 1. Save workflow (status: draft)
POST /api/workflows
{
  "name": "Auto-import Paystack",
  "nodes": [...],
  "connections": [...]
}
→ Workflow saved, NOT scheduled

// 2. Activate workflow (creates schedule)
POST /api/workflows/{id}/activate
{
  "id": "workflow-uuid"
}
→ Response:
{
  "workflow": { "status": "active", ... },
  "scheduleId": "schedule-uuid",
  "cronExpression": "0 0 * * *",
  "nextRunAt": "2025-11-29T00:00:00Z"
}
→ Status badge shows "● Active" (green)
→ Scheduler begins executing daily

// 3. Pause workflow (disables schedule)
POST /api/workflows/{id}/pause
{
  "id": "workflow-uuid"
}
→ Response:
{
  "workflow": { "status": "paused", ... },
  "success": true
}
→ Status badge shows "⏸⏸ Paused" (yellow)
→ Schedule preserved but disabled

// 4. Re-activate (re-enables existing schedule)
POST /api/workflows/{id}/activate
→ Same schedule reactivated
→ Status returns to "active"

Scheduler Implementation

// WorkflowScheduler (Go)

type WorkflowScheduler struct {
    cron         *cron.Cron
    db           *database.DB
    scheduleMap  map[string]cron.EntryID
    workflowRunner *WorkflowRunner
}

// Start - Called on app startup
func (s *WorkflowScheduler) Start(ctx context.Context) {
    s.cron.Start()
    s.LoadActiveSchedules(ctx)
    go s.refreshLoop(ctx)  // Reload every 5 min
}

// ConvertPollingIntervalToCron
func ConvertPollingIntervalToCron(interval string) string {
    cronMap := map[string]string{
        "15":   "*/15 * * * *",  // Every 15 minutes
        "30":   "*/30 * * * *",  // Every 30 minutes
        "60":   "0 * * * *",     // Every hour
        "360":  "0 */6 * * *",   // Every 6 hours
        "1440": "0 0 * * *",     // Daily at midnight
    }
    return cronMap[interval]
}

// CreateOrUpdateScheduleForWorkflow
func (s *WorkflowScheduler) CreateOrUpdateScheduleForWorkflow(
    workflowID, tenantID uuid.UUID, 
    pollingInterval string
) (*models.WorkflowSchedule, error) {
    cronExpr := ConvertPollingIntervalToCron(pollingInterval)
    
    // Check if schedule exists
    var existing models.WorkflowSchedule
    if found {
        // Update cron and re-add to scheduler
        existing.CronExpression = cronExpr
        existing.IsActive = true
        db.Save(&existing)
        s.RemoveSchedule(existing.ID)
        s.AddSchedule(ctx, &existing)
        return &existing, nil
    }
    
    // Create new schedule
    return s.CreateSchedule(workflowID, tenantID, cronExpr, "UTC")
}

// executeScheduledWorkflow - Run workflow on schedule
func (s *WorkflowScheduler) executeScheduledWorkflow(
    ctx context.Context, 
    schedule *models.WorkflowSchedule
) {
    // Check workflow status
    var workflow models.Workflow
    db.Where("id = ?", schedule.WorkflowID).First(&workflow)
    
    if workflow.Status != "active" {
        log.Printf("Skipping workflow %s: status is '%s'", 
            schedule.WorkflowID, workflow.Status)
        return
    }
    
    // Update last_run_at, calculate next_run_at
    now := time.Now()
    nextRun := cronSchedule.Next(now)
    db.Model(schedule).Updates(map[string]interface{}{
        "last_run_at": now,
        "next_run_at": nextRun,
    })
    
    // Execute workflow
    s.workflowRunner.ExecuteWorkflow(
        ctx, 
        schedule.WorkflowID, 
        schedule.TenantID,
        models.TriggerTypeSchedule, 
        nil
    )
}

Frontend Activation Controls

// workflow-builder-v2.tsx

const [currentWorkflow, setCurrentWorkflow] = useState<{
  id: string
  name: string
  status?: string  // 'draft' | 'active' | 'paused'
}>(null)

const activateWorkflow = async () => {
  const response = await fetch(
    `/api/workflows/${currentWorkflow.id}/activate`, 
    { method: 'POST' }
  )
  const data = await response.json()
  showToast(
    `Workflow activated! Next run: ${new Date(data.nextRunAt).toLocaleString()}`,
    "success"
  )
  setCurrentWorkflow({ ...currentWorkflow, status: 'active' })
}

const pauseWorkflow = async () => {
  await fetch(`/api/workflows/${currentWorkflow.id}/pause`, { method: 'POST' })
  showToast("Workflow paused", "success")
  setCurrentWorkflow({ ...currentWorkflow, status: 'paused' })
}

// UI - Status badge
{currentWorkflow?.status && (
  <span className={`badge ${
    currentWorkflow.status === 'active' ? 'badge-success' :
    currentWorkflow.status === 'paused' ? 'badge-warning' :
    'badge-secondary'
  }`}>
    {currentWorkflow.status === 'active' ? '● Active' :
     currentWorkflow.status === 'paused' ? '⏸⏸ Paused' :
     '○ Draft'}
  </span>
)}

// UI - Activate/Pause button
{currentWorkflow?.status === 'active' ? (
  <Button onClick={pauseWorkflow}>Pause</Button>
) : (
  <Button onClick={activateWorkflow}>Activate</Button>
)}

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

📧 Email System Production Ready

Overview

Template-based email system with Sparkpost integration, dynamic recipients, file attachments, and workflow automation. All emails use HTML templates with automatic plain text generation.

Key Features

• ✅ Template-only email system (no custom HTML)
• ✅ Sparkpost API integration with sandbox mode
• ✅ Dynamic recipient resolution (tenant_admin, user, contact, custom)
• ✅ File attachments (CSV, PDF, receipts)
• ✅ Variable substitution with {{variable}} syntax
• ✅ Multiple recipients (To, CC, BCC)
• ✅ Auto-generated plain text from HTML
• ✅ Beautiful responsive email templates
• ✅ Workflow integration via send_email node
• ✅ Schema-driven frontend config UI (composable, dynamic, no hardcoded conditions)

Email Architecture

┌──────────────────────────────────────────────────┐
│         Workflow Email Node (send_email)         │
│  • Template selection (required)                 │
│  • Recipient configuration                       │
│  • Subject with variables                        │
│  • Attachment configuration                      │
└────────────────┬─────────────────────────────────┘
                 │
                 ▼
┌──────────────────────────────────────────────────┐
│        Email Executor (Go Backend)               │
│  ┌────────────────────────────────────────────┐ │
│  │  1. Resolve Recipients                     │ │
│  │     • tenant_admin → Tenant owner          │ │
│  │     • user → From workflow context         │ │
│  │     • contact → From payment/transaction   │ │
│  │     • custom → Static email list           │ │
│  └────────────┬───────────────────────────────┘ │
│               ▼                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  2. Prepare Template Data                  │ │
│  │     • Flatten payment/contact data         │ │
│  │     • Add workflow metadata                │ │
│  │     • Merge custom data from config        │ │
│  │     • Replace {{variables}}                │ │
│  └────────────┬───────────────────────────────┘ │
│               ▼                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  3. Render Template (html/template)        │ │
│  │     • Load from templates/emails/          │ │
│  │     • Execute with template data           │ │
│  │     • Generate plain text version          │ │
│  └────────────┬───────────────────────────────┘ │
│               ▼                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  4. Generate Attachments                   │ │
│  │     • payment_receipt → PDF/HTML           │ │
│  │     • csv_export → CSV from data           │ │
│  │     • financial_report → Comprehensive PDF │ │
│  │     • Base64 encode for API                │ │
│  └────────────┬───────────────────────────────┘ │
│               ▼                                  │
│  ┌────────────────────────────────────────────┐ │
│  │  5. Send via Sparkpost API                 │ │
│  │     • POST /transmissions                  │ │
│  │     • Multiple recipients (To/CC/BCC)      │ │
│  │     • Attachments with base64 encoding     │ │
│  │     • Sandbox mode for development         │ │
│  └────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────┘

Built-in Email Templates

Recipient Resolution Types

Email Node Configuration Example

// Payment notification with receipt
{
  "type": "send_email",
  "config": {
    "template": "payment_received",
    "recipients": {
      "type": "contact",
      "email_field": "created_payment.contact_email",
      "name_field": "created_payment.contact_name",
      "cc_tenant": true  // CC tenant admin
    },
    "subject": "Payment Received - {{reference}}",
    "attachments": [
      {
        "type": "payment_receipt",
        "filename": "receipt_{{reference}}.pdf"
      }
    ],
    "data": {
      "recipient_name": "{{contact_name}}",
      "dashboard_url": "https://app.company.com"
    }
  }
}

Attachment Types

Variable Substitution

Use {{variable}} syntax with dot notation for nested values:

// Automatically available variables
{{workflow_id}}           // Current workflow ID
{{execution_id}}          // Current execution ID
{{tenant_name}}           // Tenant company name
{{current_date}}          // YYYY-MM-DD format
{{current_datetime}}      // RFC3339 format
{{dashboard_url}}         // Dashboard base URL

// Flattened payment data (from created_payment)
{{amount}}                // Payment amount
{{currency}}              // Payment currency (USD, NGN, etc.)
{{reference}}             // Payment reference
{{description}}           // Payment description
{{payment_method}}        // Payment method (card, bank_transfer)
{{transaction_date}}      // Transaction date
{{payment_id}}            // Payment UUID

// Flattened contact data (from created_contact)
{{contact_name}}          // Contact full name
{{contact_email}}         // Contact email
{{contact_phone}}         // Contact phone

// Nested access from workflow context
{{created_payment.metadata.custom_field}}
{{loop_item.customer.name}}

Environment Configuration

# Sparkpost API Configuration
SPARKPOST_API_KEY=your_sparkpost_api_key
SPARKPOST_API_URL=https://api.sparkpost.com/api/v1

# Email Defaults
EMAIL_FROM_ADDRESS=noreply@yourdomain.com
EMAIL_FROM_NAME=Keepfig

# Environment (affects sandbox mode)
ENVIRONMENT=production  # development enables sandbox mode

Sparkpost Setup Steps

1. Get API Key: Log in to Sparkpost dashboard → API Keys → Create New Key
2. Verify Domain: Account → Sending Domains → Add Domain
3. Add DNS Records: Copy DKIM and SPF records to Namecheap DNS
4. DKIM: TXT record like scph1234._domainkey → v=DKIM1; k=rsa; p=...
5. SPF: TXT record @ → v=spf1 include:sparkpostmail.com ~all
6. Verify: Wait 24-48h for DNS propagation, click Verify in Sparkpost
7. Test: Use sandbox mode (ENVIRONMENT=development) for testing

Pricing

• ✅ First 500 emails/month: FREE
• ✅ 501-100K emails: $0.20 per 1,000 emails
• ✅ Very cost-effective for transactional emails

Schema-Driven Configuration UI

The workflow builder uses a dynamic, composable configuration system instead of hardcoded conditions for each node type. This makes it easy to add new node types without frontend code changes.

How It Works

1. Backend Schema: Node types define config_schema in JSON (e.g., actions.json)
2. Dynamic Renderer: DynamicConfigRenderer component reads the schema and generates UI
3. Field Types: text, textarea, select, boolean, number, array, object (nested configs)
4. Conditional Fields: required_when shows/hides fields based on parent values
5. Template Metadata: Each email template option includes required_data, suggested_recipients, supports_attachments

Example: send_email Config Schema

{
  "template": {
    "type": "select",
    "label": "Email Template",
    "required": true,
    "options": [
      {
        "value": "payment_received",
        "label": "Payment Received",
        "description": "Payment confirmation with receipt",
        "required_data": ["amount", "currency", "reference"],
        "suggested_recipients": ["contact"],
        "supports_attachments": ["payment_receipt"]
      }
    ]
  },
  "recipients": {
    "type": "object",
    "properties": {
      "type": {
        "type": "select",
        "options": [
          { "value": "tenant_admin", "label": "Tenant Owner/Admin" },
          { "value": "user", "label": "User from Context" },
          { "value": "contact", "label": "Contact from Payment" },
          { "value": "custom", "label": "Custom Email List" }
        ]
      },
      "email_field": {
        "type": "text",
        "required_when": ["user", "contact"],
        "placeholder": "team_member.email"
      }
    }
  }
}

Benefits

• ✅ No Frontend Code Changes: Add new node types by updating JSON only
• ✅ Consistent UI: All nodes use same styling and behavior
• ✅ Self-Documenting: Schema includes labels, descriptions, placeholders
• ✅ Type-Safe: Field types ensure correct data format
• ✅ Conditional Logic: Show/hide fields based on other values
• ✅ Maintainable: Eliminates 1000+ lines of hardcoded if/else conditions

Common Workflow Patterns

1. Payment Notification Flow

paystack_sync → create_payment → send_email (payment_received)
                                         ↓
                              Store payment in DB
                                         ↓
                              Email customer with receipt

2. Workflow Status Notifications

// Success notification
[workflow completes] → send_email (workflow_success to admin)

// Failure notification  
[workflow fails] → send_email (workflow_failed to admin)

3. Scheduled Reports

[cron: daily at midnight]
  ↓
generate_report_data
  ↓
send_email (financial_report with CSV attachment)

4. Conditional Notifications

create_payment
  ↓
condition (amount > 10000)
  ↓ (true)
send_email (high_value_payment alert to CFO)

🔒 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/invoice_pro_db
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 invoice_pro_db

# 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

🛡️ Fraud Detection API Standard

Response Structure Overview

All verification responses follow a standardized structure with clear decisions, signals, and recommendations:

message VerificationResult {
  // Identifiers
  string verification_id = 1;
  string document_hash_id = 2;
  
  // Decision (ACCEPT/REVIEW/REJECT)
  VerificationDecision decision = 5;
  string recommendation = 6;
  
  // Risk Assessment
  double risk_score = 7;        // 0.0 to 1.0
  string risk_level = 8;        // low, medium, high, critical
  double confidence = 9;        // 0.0 to 1.0
  
  // Individual fraud indicators
  repeated DetectionSignal signals = 10;
  
  // Duplicate detection results
  DuplicateAnalysis duplicate_analysis = 11;
  
  // Visual similarity (recurring vendors)
  SimilarityAnalysis similarity_analysis = 12;
  
  // Processing metadata
  ProcessingInfo processing_info = 13;
}

Decision Types

Detection Signals

Each signal represents an individual fraud indicator with its own confidence and risk contribution:

message DetectionSignal {
  string signal_type = 1;        // duplicate_hash, visual_similarity, etc.
  string category = 2;           // duplicate_detection, image_forensics, etc.
  string severity = 3;           // info, low, medium, high, critical
  string description = 4;        // Human-readable description
  double confidence = 5;         // 0.0 to 1.0
  double risk_contribution = 6;  // How much this adds to risk score
  map<string, string> metadata = 7;
  string phase = 8;              // Which phase detected this signal
}

Signal Categories

• duplicate_detection: Exact hash match, invoice number match, metadata-verified duplicate
• image_forensics: EXIF analysis, ELA (Error Level Analysis), copy-move detection
• pdf_forensics: Metadata extraction, incremental updates, structure analysis
• ocr_extraction: Invoice number, amount, merchant name extraction

Common Signal Types

Duplicate vs Similarity Analysis

DuplicateAnalysis - True Duplicates

Confirmed duplicates that should be rejected:

message DuplicateAnalysis {
  bool is_duplicate = 1;
  string detection_method = 2;        // "exact_hash", "invoice_number", "metadata_verified"
  repeated string duplicate_document_ids = 3;
  double match_confidence = 4;        // Typically 0.95+ for true duplicates
  string explanation = 5;
}

SimilarityAnalysis - Recurring Vendors

Visual similarity that's NOT a duplicate (legitimate recurring transactions):

message SimilarityAnalysis {
  bool has_similar_documents = 1;
  int32 similar_document_count = 2;
  repeated SimilarDocument similar_documents = 3;
  string interpretation = 4;          // "recurring_vendor", "same_template"
  string recommendation = 5;
}

message SimilarDocument {
  string document_id = 1;
  double visual_similarity_score = 2;  // 0.0 to 1.0
  int32 hamming_distance = 3;          // Perceptual hash distance
  DifferentiatingFactors differentiating_factors = 4;
}

Differentiating Factors

Shows WHY visually similar documents are NOT duplicates:

message DifferentiatingFactors {
  bool different_invoice_numbers = 1;
  bool different_amounts = 2;
  bool different_dates = 3;
  string amount_difference = 4;       // "$52.00 vs $26.00"
  string date_difference = 5;         // "Oct 2025 vs Dec 2025"
  string invoice_numbers = 6;         // "#256348 vs #284081"
}

Processing Info

Multi-phase forensics tracking:

message ProcessingInfo {
  repeated string phases_completed = 1;   // ["hash", "ocr", "image_forensics"]
  repeated string phases_pending = 2;     // ["deep_analysis"]
  int64 processing_duration_ms = 3;
  string processed_by = 4;                // Service version
  map<string, string> phase_timings = 5;
}

Forensics Phases (Multi-Phase Architecture)

1. Phase 1 - Hash Analysis: SHA-256 + perceptual hash (exact + visual similarity)
2. Phase 2 - OCR Extraction: Invoice number, amount, merchant (docTR/PaddleOCR)
3. Phase 3 - Image Forensics: EXIF, ELA, copy-move detection (if image)
4. Phase 4 - PDF Forensics: Metadata, structure, timestamps (if PDF)
5. Phase 5 - Metadata Verification: Cross-reference to determine true duplicates
6. Phase 6 - Deep Analysis (Future): ML-based anomaly detection, behavioral patterns

Example Responses

Scenario 1: Confirmed Duplicate (REJECT)

{
  "verification_id": "abc123...",
  "decision": "REJECT",
  "recommendation": "REJECT: This document is a confirmed duplicate. Do not process to avoid duplicate payments.",
  "risk_score": 0.95,
  "risk_level": "critical",
  "confidence": 0.98,
  
  "signals": [
    {
      "signal_type": "duplicate_invoice_number",
      "category": "duplicate_detection",
      "severity": "critical",
      "description": "Invoice number #284081 already exists in system",
      "confidence": 0.99,
      "risk_contribution": 0.6
    }
  ],
  
  "duplicate_analysis": {
    "is_duplicate": true,
    "detection_method": "invoice_number_match",
    "duplicate_document_ids": ["def456..."],
    "match_confidence": 0.99,
    "explanation": "Duplicate invoice number detected: #284081"
  },
  
  "similarity_analysis": {
    "has_similar_documents": false
  }
}

Scenario 2: Recurring Vendor (ACCEPT)

{
  "verification_id": "xyz789...",
  "decision": "ACCEPT",
  "recommendation": "ACCEPT: Visual similarity detected with previous documents (likely recurring vendor/template), but metadata confirms this is a unique transaction. Safe to process.",
  "risk_score": 0.15,
  "risk_level": "low",
  "confidence": 0.92,
  
  "signals": [],
  
  "duplicate_analysis": {
    "is_duplicate": false,
    "detection_method": "metadata_verified_unique",
    "match_confidence": 0.0,
    "explanation": "No duplicates detected. Document is unique."
  },
  
  "similarity_analysis": {
    "has_similar_documents": true,
    "similar_document_count": 2,
    "similar_documents": [
      {
        "document_id": "abc123...",
        "visual_similarity_score": 0.92,
        "hamming_distance": 3,
        "differentiating_factors": {
          "different_invoice_numbers": true,
          "different_amounts": true,
          "different_dates": true,
          "amount_difference": "$52.00 vs $26.00",
          "date_difference": "Oct 2025 vs Dec 2025",
          "invoice_numbers": "#256348 vs #284081"
        }
      }
    ],
    "interpretation": "recurring_vendor",
    "recommendation": "Visual similarity detected with previous documents. This appears to be from the same vendor/template with different transaction details. Document is unique and safe to process."
  }
}

Scenario 3: Medium Risk (REVIEW)

{
  "verification_id": "review123...",
  "decision": "REVIEW",
  "recommendation": "REVIEW: Elevated risk detected (medium). Please verify document authenticity before processing.",
  "risk_score": 0.55,
  "risk_level": "medium",
  "confidence": 0.78,
  
  "signals": [
    {
      "signal_type": "ela_suspicious",
      "category": "image_forensics",
      "severity": "medium",
      "description": "Error Level Analysis indicates possible manipulation",
      "confidence": 0.75,
      "risk_contribution": 0.3
    },
    {
      "signal_type": "no_exif_data",
      "category": "image_forensics",
      "severity": "low",
      "description": "Image missing EXIF metadata",
      "confidence": 0.9,
      "risk_contribution": 0.1
    }
  ],
  
  "duplicate_analysis": {
    "is_duplicate": false
  },
  
  "similarity_analysis": {
    "has_similar_documents": false
  }
}

Frontend Integration

TypeScript Client Usage

import { FraudDetectionApiClient } from '@/lib/fraud-detection/api-client';

// Upload document for verification
const result = await fraudClient.verifyDocument(file, {
  gdprConsent: true,
  consentFields: {
    purpose: 'fraud_detection',
    retention: '90_days'
  }
});

// Handle decision
switch (result.decision) {
  case 'ACCEPT':
    // Process document automatically
    console.log('✅', result.recommendation);
    await processDocument(result.verificationId);
    break;
    
  case 'REVIEW':
    // Flag for manual review
    console.log('⚠️', result.recommendation);
    await flagForReview(result.verificationId);
    break;
    
  case 'REJECT':
    // Block document
    console.log('🚫', result.recommendation);
    await rejectDocument(result.verificationId);
    break;
}

// Show similarity info if present
if (result.similarityAnalysis?.hasSimilarDocuments) {
  console.log('ℹ️ Recurring vendor detected:', 
    result.similarityAnalysis.recommendation);
}

UI Display Patterns

Best Practices

Future Phases (Roadmap)

• Phase 7 - Machine Learning: Behavioral pattern recognition, anomaly detection
• Phase 8 - Network Analysis: Cross-tenant fraud rings, vendor reputation scoring
• Phase 9 - Real-time Monitoring: Live fraud detection dashboard, alert system
• Phase 10 - Blockchain Verification: Immutable audit trails, supplier verification

Logging & Observability

Architecture Overview

Keepfig uses industry-standard logging stack for centralized log management:

Features

• Automatic Log Collection: Auto-discovers all Docker containers via labels
• Centralized Storage: All logs in one place with 30-day retention
• Real-time Search: Query logs across all services instantly
• Pre-built Dashboard: "Keepfig - Application Logs" dashboard included
• Label Extraction: Automatically tags logs with service, container, level
• JSON Parsing: Structured log parsing for better searchability
• Cost-Effective: Label-based indexing (not full-text) saves storage

Quick Start

Development

# Start all services including logging
docker-compose up -d

# Access Grafana
open http://localhost:3000
# Login: admin / admin

Production

# Set secure Grafana password
export GRAFANA_ADMIN_PASSWORD="your-secure-password"

# Deploy with logging
docker-compose -f docker-compose.prod.yml up -d

# Access Grafana
open http://your-server:3000

Using Grafana

Pre-configured Dashboard

Navigate to: Dashboards → Invoice Pro - Application Logs

Dashboard Panels:

• Backend Logs: Fraud detection, currency conversion, verification
• OCR Service Logs: PaddleOCR extraction, currency detection
• Backend Errors: All ERROR/CRITICAL/Failed logs
• Log Rate by Service: Real-time log volume chart

LogQL Query Examples

# All backend logs
{service="backend"}

# Fraud detection logs
{service="backend"} |~ "VerifyDocument|GetVerificationResult"

# Currency conversion logs
{service="backend"} |~ "convertToBaseCurrency|Currency"

# OCR service logs
{service="ocr-service"}

# All errors across all services
{project="invoice-pro"} |~ "ERROR|CRITICAL|Failed"

# Search by verification ID (distributed tracing)
{service="backend"} |~ "VerificationID=abc-123-def-456"

# Count errors per service
sum by (service) (count_over_time({project="invoice-pro"} |~ "ERROR" [5m]))

Log Retention

• Default Retention: 30 days (720 hours)
• Storage Location: Docker volume loki_data
• Auto-cleanup: Enabled (logs older than 30 days deleted automatically)
• Storage Cost: ~50MB/day, ~1.5GB/month

Adjust Retention: Edit loki-config.yaml

limits_config:
  retention_period: 720h  # Change to desired hours

Security Best Practices

Troubleshooting

Logs Not Appearing

# Check Promtail is running
docker-compose ps promtail
docker-compose logs promtail

# Verify Loki is accessible
curl http://localhost:3100/ready
# Should return: ready

# Check Docker labels
docker inspect invoice-pro-backend-1 | grep com.docker.compose.service

Grafana Can't Connect to Loki

# Test network connectivity
docker-compose exec grafana ping loki

# Check datasource in Grafana UI
# Configuration → Data Sources → Loki
# URL should be: http://loki:3100

High Disk Usage

# Check Loki storage
docker-compose exec loki du -sh /loki

# Reduce retention in loki-config.yaml
# Then restart
docker-compose restart loki

OCR Service Build Timeout

Models are lazy-loaded at startup (not during build) to avoid GitHub Actions timeout:

• Docker Build: Completes in under 5 minutes (no model download)
• First Startup: Downloads models (~25MB) in 30-60 seconds
• Service Ready: Health check passes after model initialization
• All Requests: Fast (models cached after first startup)

# Check OCR service status
docker compose -f docker-compose.prod.yml ps ocr-service

# Watch model download during first startup
docker compose -f docker-compose.prod.yml logs ocr-service -f
# Look for: "Initializing CPU-optimized docTR OCR predictor (first request)..."
# Look for: "CPU-optimized docTR OCR predictor initialized successfully"

# Test health endpoint (should return after model download)
curl http://localhost:8001/health
# Should return: {"status": "healthy"}

Integration with Application

Backend (Go)

Logs automatically collected via stdout/stderr. Use structured logging:

log.Printf("[VerifyDocument] TenantID=%s, Amount=%.2f %s, Decision=%s",
    tenantID, amount, currency, decision)

OCR Service (Python)

import logging
logger = logging.getLogger(__name__)
logger.info(f"Detected currency: {currency} with confidence {confidence}")

Add Correlation IDs

log.Printf("[RequestID=%s] Processing verification...", requestID)

# Search in Grafana:
{service="backend"} |~ "RequestID=abc-123"

Cost Analysis

Annual Savings: $300-900 compared to commercial alternatives

Recent Updates (December 2025)

Universal Currency Detection

Enhancements

• Regex Pattern Matching: Detects ANY ISO 4217 currency code (3-letter format)
• 100+ Priority Currencies: Intelligent matching for common currencies
• Global Symbol Support: African (₦, ₵), Asian (¥, ₹, ₩, ฿), Latin American (R$) currencies
• No Configuration Required: Automatically works with invoices from any country

Example Supported Currencies

Europe: EUR €, GBP £, CHF, SEK kr, NOK kr, DKK kr, PLN zł
Africa: NGN ₦, ZAR R, GHS ₵, KES KSh, EGP £
Asia: JPY ¥, CNY ¥, INR ₹, KRW ₩, THB ฿, SGD $, HKD $
Americas: USD $, CAD $, BRL R$, MXN $, ARS $, CLP $
Middle East: AED د.إ, SAR ر.س, ILS ₪

How It Works

def detect_currency(text: str) -> str:
    # 1. Search for any 3-letter ISO code pattern
    currency_pattern = r'\b([A-Z]{3})\b'
    matches = re.findall(currency_pattern, text_upper)
    
    # 2. Prioritize common currencies if multiple found
    # 3. Fallback to symbol detection (€, $, £, ¥, ₹, ₽, ₦, etc.)
    # 4. Context-aware disambiguation for ambiguous symbols

Files Updated: ocr-service/app/main.py, backend/internal/accountingserver/forensics.go

Enhanced Similar Documents Display

New Information Displayed

When similar documents are detected (not duplicates), the UI now shows:

• Document ID: Full UUID for precise identification
• Document Hash (SHA-256): Cryptographic hash of document
• Perceptual Hash: Visual similarity hash for comparison
• Hamming Distance: Numeric measure of visual similarity (0-64)
• Visual Similarity Score: Percentage match (0-100%)
• Upload Timestamp: When the similar document was uploaded
• Differentiating Factors: Why documents are NOT duplicates
  • Different invoice numbers with actual values shown
  • Different amounts with comparison
  • Different dates with comparison
• View Details Link: Navigate to full verification details

Visual Design

┌────────────────────────────────────────────────┐
│ Similar Documents Found:                       │
├────────────────────────────────────────────────┤
│ Document ID: abc-123-def-456...                │
│ Visual Similarity: 87%                         │
│                                                │
│ SHA-256 Hash: a1b2c3d4e5f6...                 │
│ Perceptual Hash: 1a2b3c4d5e6f...              │
│ Hamming Distance: 8 (Similar)                  │
│                                                │
│ Uploaded: Dec 3, 2025, 10:30 AM               │
│                                                │
│ ✓ Why This Is NOT a Duplicate:                │
│   ✓ Different Invoice Numbers                 │
│     #256348 vs #284081                         │
│   ✓ Different Amounts                          │
│     $52.00 vs $26.00                           │
│   ✓ Different Dates                            │
│     Oct 2025 vs Dec 2025                       │
│                                                │
│ View Full Details →                            │
└────────────────────────────────────────────────┘

Files Updated: proto/forensics.proto, forensics.go, use-fraud-detection.ts, fraud-check-results.tsx

Deployment Checklist

Required GitHub Secrets

Deployment Steps

1. Configure GitHub Secrets:
   • Go to repository Settings → Secrets and variables → Actions
   • Add each secret from the table above
   • Use strong passwords for ENV_POSTGRES and ENV_GRAFANA
2. Push to Main: Automatic deployment triggers on push to main branch
3. Verify Services:

   ssh root@your-server
   cd ~/invoice-pro
   ./deploy.sh monitor  # Check all services are running

4. Access Grafana: http://your-server:3001 (admin credentials from ENV_GRAFANA)
5. Test Logging: Upload invoice → Check logs in Grafana dashboard

Manual Deployment (Optional)

# SSH into server
ssh root@your-server

# Navigate to project
cd ~/invoice-pro

# Pull latest changes
git pull origin main

# Deploy all services
./deploy.sh deploy

# Monitor health
./deploy.sh monitor

Services Deployed

• ✅ Backend: gRPC API server (port 50052)
• ✅ OCR Service: PaddleOCR document extraction (port 8001)
• ✅ Extractor: Google Document AI integration
• ✅ Loki: Log aggregation (port 3100)
• ✅ Promtail: Log collector
• ✅ Grafana: Log visualization (port 3001)
• ✅ Envoy: gRPC-web proxy (ports 8080/8443)
• ✅ PostgreSQL: Database (port 5432)
• ✅ Redis: Cache (port 6379)

Post-Deployment Verification

1. Regenerate Protobuf: make proto-go
2. Rebuild Services: docker-compose build backend ocr-service
3. Deploy: docker-compose up -d
4. Verify Grafana: open http://localhost:3001
5. Test Currency Detection: Upload invoices with various currencies
6. Test Similar Documents: Upload recurring vendor invoices