Backend Services

gRPC servers, business logic services, and background workers.

Service Architecture

The backend follows a layered architecture: gRPC servers handle requests, delegate to services for business logic, which interact with the database.

Directory Structure

backend/internal/
├── authserver/          # Auth gRPC handlers
├── orgserver/           # Org & Workspace handlers
├── accountingserver/    # Accounting handlers
├── paymentv3server/     # Payment V3 handlers
├── taxserver/           # Tax handlers
├── grpcserver/          # Invoice extraction handlers
├── services/            # Business logic (shared)
├── models/              # GORM database models
├── database/            # DB connection & queries
├── middleware/          # Auth, rate limiting
├── worker/              # Background processors
└── workflow/            # Workflow executors

gRPC Servers

Each gRPC server implements a proto service and handles request/response translation.

AuthServer

User authentication and session management.

Register - Create new user account
Login - Authenticate and return JWT
RefreshToken - Renew JWT before expiry
ResetPassword - Password recovery flow

Location: backend/internal/authserver/

OrganizationServer & WorkspaceServer

Multi-tenancy management.

CreateOrganization - New billing entity
CreateWorkspace - New data container
InviteTeamMember - Send email invitation
UpdateSubscription - Change plan tier

Location: backend/internal/orgserver/

AccountingServer

Dashboard, reports, chart of accounts, AI chat.

GetDashboardStats - Revenue, expenses, profit
ListJournalEntries - Double-entry ledger
GetChartOfAccounts - Account structure
ChatWithAI - AI assistant queries

Location: backend/internal/accountingserver/

PaymentV3Server

Transaction CRUD and bulk operations.

CreateTransaction - New income/expense
ListTransactions - Paginated list with filters
BulkCreateTransactions - Import multiple
PostTransaction - Commit to ledger

Location: backend/internal/paymentv3server/

TaxServer

Tax profiles, calculations, and compliance.

CreateTaxProfile - Define tax rules
CalculateTax - Compute VAT/WHT
GetTaxReport - Period tax summary
ListJurisdictions - Supported countries

Location: backend/internal/taxserver/

InvoiceExtractionServer

Document upload and OCR processing.

ExtractInvoice - Upload and queue for extraction
GetExtractionStatus - Check processing status
ListExtractions - History of extractions

Location: backend/internal/grpcserver/

Business Logic Services

Services contain all business rules. Servers only handle request translation.

Rule: All database queries must go through services. Never put DB queries directly in server handlers.

Core Services

backend/internal/services/
├── transaction_service.go    # Transaction CRUD
├── journal_service.go        # Journal entries
├── journal_generation_service.go  # Auto-generate journals
├── category_service.go       # Categories
├── account_service.go        # Chart of accounts
├── currency_service.go       # FX rates
├── dashboard_service.go      # Dashboard stats
├── organization_service.go   # Org management
├── workspace_service.go      # Workspace management
├── team_service.go          # Team invitations

Tax Services

backend/internal/services/
├── tax_management_service.go # Tax profiles
├── tax_profile_resolver.go   # Resolve tax rules
└── tax/
    └── tax_calculation_service.go  # Compute taxes

AI Services

backend/internal/services/
├── ai_agent_service.go       # OpenAI integration
├── smart_categorization_service.go  # Auto-categorize
├── smart_capture_service.go  # Receipt parsing

Data Import System

Supports CSV and Excel imports with AI-powered column mapping.

Import Flow

Upload - User uploads CSV/Excel via frontend
Parse - ImportParserService extracts headers and sample rows
AI Mapping - ImportMapperService uses OpenAI to suggest column mappings
Review - User confirms/adjusts mappings in UI
Process - ImportWorker processes rows via Redis queue
Create - Transactions created with journal entries

Import Services

backend/internal/services/
├── import_service.go         # Main orchestrator
├── import_parser_service.go  # CSV/Excel parsing
├── import_mapper_service.go  # AI column mapping
└── summary_import_service.go # Summary imports

Supported Formats

CSV files with headers
Excel files (.xlsx, .xls)
Bank statement exports
QuickBooks export format

Workflow Engine

Visual automation builder with triggers, conditions, and actions.

Components

WorkflowScheduler - Watches for trigger events, queues workflows
WorkflowRunner - Executes nodes in sequence/parallel
ExecutorRegistry - Maps node types to executors
Node Executors - Email, Slack, conditions, delays

Triggers

Transaction created
Transaction updated
Invoice overdue
Payment received
Scheduled (cron)

Actions

Send email
Send Slack message
Create transaction
Update fields
HTTP webhook

Workflow Files

backend/internal/
├── services/
│   ├── workflow_runner.go     # Execution engine
│   └── workflow_scheduler.go  # Trigger monitoring
└── workflow/
    └── executors/             # Node implementations
        ├── email_executor.go
        ├── slack_executor.go
        ├── condition_executor.go
        └── delay_executor.go

Background Workers

Long-running tasks are processed asynchronously via Redis queues.

Worker Types

ExtractionWorker - Document OCR and AI extraction
ImportWorker - CSV/Excel import processing
ForensicsWorker - Deep document fraud analysis
RevenueCatWorker - Subscription webhook events
SessionCleanupWorker - Expired session cleanup
TrialExpiryWorker - Trial expiration notifications

Queue Names

extraction:jobs        # Document extraction
forensics:deep_analysis # Deep forensics
webhooks:revenuecat    # Subscription webhooks
import:jobs            # CSV/Excel imports

Worker Files

backend/internal/worker/
├── worker.go              # Extraction worker
├── import_worker.go       # Import processing
├── forensics_worker.go    # Document analysis
├── revenuecat_worker.go   # Subscription webhooks
├── session_cleanup.go     # Session cleanup
└── trial_expiry.go        # Trial notifications

Architecture Transport