System Architecture

High-Level Overview


┌────────────────────────────────────────────────────────┐
│               SendAfrica Web Dashboard                 │
│         (In-app Chat Widget at /admin or /app)          │
└──────────────────────────┬─────────────────────────────┘
                           │ POST /v1/support/chat
                           ▼
┌────────────────────────────────────────────────────────┐
│               SendAfrica Go Core API                   │
│             (https://api.sendafrica.online)            │
└──────────────────────────┬─────────────────────────────┘
                           │ Proxy to AGENT_SERVICE_URL
                           ▼
┌────────────────────────────────────────────────────────┐
│             SendAfrica Agent Service                   │
│  - Session History (agent_sessions / agent_messages)   │
│  - Knowledge Base System Prompt Resource               │
│  - Tool-Calling Loop with Ngamia LLM Gateway           │
│  - Safety Guardrail (Confirm-Before-Send)              │
└──────────────┬──────────────────────────┬──────────────┘
               │                          │
               │ FastMCP Tool Execution   │ Ngamia Chat Completions
               ▼                          ▼
┌─────────────────────────────┐  ┌─────────────────────────┐
│     FastMCP Server Tools    │  │   Ngamia AI Gateway     │
│   (SendAfrica & MailAfrica) │  │  (api.ngamia.cc/v1)     │
└──────────────┬──────────────┘  └─────────────────────────┘
               │
      ┌────────┴────────┐
      ▼                 ▼
┌──────────┐      ┌──────────┐
│SendAfrica│      │MailAfrica│
│ Go Core  │      │   API    │
└──────────┘      └──────────┘

Components

SendAfrica Web Dashboard

The front-end chat widget embedded in the SendAfrica dashboard. Users interact with the agent through a familiar chat interface.

SendAfrica Go Core API

The main backend API at api.sendafrica.online that proxies chat requests to the agent service.

SendAfrica Agent Service

The core Python service that:

Receives chat messages via POST /v1/agent/chat
Loads session history from SQLite
Sends messages to the Ngamia LLM gateway with tool schemas
Executes tools when the LLM requests them
Returns the final response

Ngamia AI Gateway

An OpenAI-compatible LLM gateway at api.ngamia.cc/v1 that routes requests to various models (default: openai/gpt-4o-mini).

FastMCP Server

Exposes tools via the Model Context Protocol:

Stdio mode — For direct integration with AI assistants
SSE mode — Mounted at /sse in the FastAPI app for remote access

SendAfrica & MailAfrica APIs

The upstream APIs that the agent’s tools interact with:

SendAfrica — SMS sending, contacts, campaigns, billing
MailAfrica — Email sending, inbound messages, billing

Database Schema

agent_sessions

Column	Type	Description
session_id	TEXT	Unique session identifier
account_id	TEXT	Business account ID
user_id	TEXT	User ID within the account
created_at	TIMESTAMP	Session creation time

agent_messages

Column	Type	Description
id	INTEGER	Auto-increment ID
session_id	TEXT	Foreign key to sessions
role	TEXT	Message role (user/assistant/tool)
content	TEXT	Message content
tool_calls	TEXT	JSON-serialized tool calls
tool_id	TEXT	Tool call ID for tool results
created_at	TIMESTAMP	Message creation time