Architecture

System Overview

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Frontend  │────▶│   REST API   │────▶│  PostgreSQL  │
│  (Next.js)  │     │   (Go/Gin)   │     │             │
└─────────────┘     └──────┬───────┘     └─────────────┘
                           │
                    ┌──────┴───────┐
                    │  Event Bus   │
                    └──────┬───────┘
                           │
┌─────────────┐     ┌──────┴───────┐     ┌─────────────┐
│ MCP Clients │────▶│  MCP Agent   │────▶│  Ngamia AI   │
│ (Claude/Cursor)   │  (Python)    │     │  Gateway     │
└─────────────┘     └──────┬───────┘     └─────────────┘
                           │
                    ┌──────┴───────┐
                    │  External    │
                    │  Services    │
                    └──────────────┘
                    SendAfrica (SMS)
                    MailAfrica (Email)
                    MinIO (Storage)
                    Wikimedia (Images)

API Modules (Go Backend)

The Go API is organized into 17 domain modules, each with routes, handlers, services, and models:

Module	Tables	Description
`accounts`	organisations, stores, users, phone_otps, email_verification_tokens, ai_credits	Auth, registration, org management
`inventory`	categories, products, stock_adjustments	Product catalog and stock
`transactions`	transactions, transaction_lines, txn_counters	POS sales, refunds, voids
`customers`	customers	Customer profiles
`credits`	credit_tabs, credit_payments, credit_messages, credit_notes	Madeni/tabs system
`suppliers`	suppliers, supplier_deliveries, supplier_payments	Vendor management
`expenses`	expenses	Operating expenses
`staff`	(uses users table)	Employee management
`stores`	(uses stores table)	Multi-store management
`analytics`	(reads shared schema)	Dashboard KPIs
`reports`	scheduled_reports, report_exports	Report generation
`notebook`	notes	Staff memos
`subscriptions`	subscription_plans, subscriptions	Billing
`reviews`	store_reviews	Landing page reviews
`notifications`	notifications	In-app notifications
`ai`	ai_conversations, ai_messages	AI chat history
`uploads`	(files in MinIO)	File storage

Event Bus

The internal event bus decouples side effects from transaction handlers:

Event	Handler	Action
`user.registered`	accounts, subscriptions	Send welcome email, create trial
`staff.created`	accounts	SMS temp password
`transaction.created`	customers, credits	Update stats, auto-create credit tab
`transaction.refunded`	customers, credits	Reduce stats, settle tab
`transaction.voided`	credits	Settle credit tab

Agent Architecture

The MCP Agent acts as a bridge between natural language and the REST API:

User sends a question (Swahili/English)
LLM (via Ngamia gateway) interprets intent
Agent calls the appropriate MCP tools (which map to API endpoints)
API executes business logic
Agent formats the response and returns it

The agent supports multi-step operations (up to 8 tool calls per query) for complex tasks like "compare last week's sales with this week and suggest promotions."

Deployment