Architecture
SmartPay is a three-tier payment processing system designed for high security, scalability, and AI-powered decision making.
High-Level Architecture
Component Overview
Gateway (Go)
The public-facing REST API that handles all external requests.
| Responsibility | Description |
|---|---|
| Authentication | API keys, JWT, HMAC, service auth |
| Rate Limiting | Per-client request throttling |
| Request Routing | Routes to appropriate handlers |
| Audit Logging | Comprehensive request/response logging |
Wallet-Core (Go)
The secure financial engine that processes all transactions.
| Responsibility | Description |
|---|---|
| Ledger | Atomic transaction processing |
| Accounts | Multi-currency account management |
| Compliance | Transaction monitoring and alerts |
| Reconciliation | External processor reconciliation |
Agent-TS (TypeScript)
AI-powered conversational agent for natural language interactions.
| Responsibility | Description |
|---|---|
| NLU | OpenAI-powered intent recognition |
| KYC | Document validation with OCR |
| Tools | Wallet operations via function calling |
| Webhooks | WhatsApp message handling |
Data Flow
Payment Flow
Agent Message Flow
Security Layers
Network Layer
- VPC isolation for internal services
- Firewall rules restricting access
- Network policies in Kubernetes
Transport Layer
- TLS 1.3 for all external traffic
- mTLS for internal gRPC communication
- Certificate rotation policies
Application Layer
- JWT/OAuth2 authentication
- API key management with scopes
- Rate limiting per client
- Input validation and sanitization
Data Layer
- Encrypted database connections
- Comprehensive audit logging
- Idempotency keys for operations
Database Schema
Core Tables
| Table | Purpose |
|---|---|
accounts | User accounts with balances per currency |
transactions | Central transaction ledger |
subscribers | User profiles with KYC status |
nfc_cards | Card serials linked to subscribers |
agents | Agent/merchant accounts with float |
audit_log | Transaction and event audit trail |
api_keys | Third-party integration keys |
Transaction Table Schema
CREATE TABLE transactions (
id TEXT PRIMARY KEY,
request_id TEXT UNIQUE NOT NULL,
user_id TEXT NOT NULL,
recipient_id TEXT NOT NULL,
amount INTEGER NOT NULL,
currency TEXT NOT NULL,
status TEXT NOT NULL,
memo TEXT,
metadata JSONB,
created_at TIMESTAMP,
completed_at TIMESTAMP
);
Scalability
Gateway
Fully stateless, unlimited horizontal scaling behind load balancer
Agent
Stateless design with async request handling
Wallet-Core
Scale with read replicas, sharding by user_id for writes
Database
PostgreSQL with connection pooling and optimized indexes