Technology Stack
Core Technologies
| Component | Technology | Version | Purpose |
|---|---|---|---|
| Language | Go | 1.24+ | Primary programming language |
| RPC Framework | gRPC | v1.x | Service-to-service communication |
| REST Gateway | gRPC-Gateway v2 | v2.x | REST API translation from gRPC |
| API Definition | Protocol Buffers | proto3 | Message and service definitions |
| ORM | GORM | v2.x | Database operations and migrations |
| Configuration | Viper | v1.x | Configuration management |
| CLI | Cobra | v1.x | Command-line interface |
| Logging | Uber Zap | v1.x | Structured logging |
Data Layer
| Component | Technology | Purpose |
|---|---|---|
| Primary Database | PostgreSQL 15 | Production data persistence |
| Development DB | SQLite | Local development and testing |
| Cache | Redis | Optional caching layer |
| ORM | GORM | Multi-dialect database abstraction |
Database Configuration
- Max connections: 100 (configurable)
- Max idle connections: 10
- Max open connections: 50
- Connection max lifetime: 1 hour
- Supported dialects: PostgreSQL, SQLite, MySQL
Security
| Component | Technology | Purpose |
|---|---|---|
| Authorization | Custom License (JWT-based) | System-level authorization |
| Password Hashing | bcrypt | Secure credential storage |
| Field Encryption | AES / SHA-256 | Sensitive data protection |
| OIDC | CoreOS go-oidc | OpenID Connect support |
| CORS | rs/cors | Cross-origin request handling |
| TLS | Go stdlib | Transport encryption |
Infrastructure
| Component | Technology | Purpose |
|---|---|---|
| Containerization | Docker | Application packaging |
| Orchestration | Kubernetes | Production deployment |
| Configuration | Kustomize | K8s config management |
| Live Reload | Air | Development hot-reload |
| Build | Make | Build automation |
| Release | GoReleaser | Automated release builds |
External Integrations
| Service | Purpose | Integration Type |
|---|---|---|
| BLNK | Core banking engine for Kulpay digital wallet | REST API (Adapter) |
| MiniAiLive | Biometric liveness detection and face matching | REST API |
| SMS Provider | OTP delivery for phone verification | REST API |
| NUIB API | National identity verification (Mozambique) | REST API |
| Minio | Self-hosted object storage for documents and images | S3-compatible API |
| QR Code Service | In-house QR code generation and scan tracking | REST API |
| Card Simo | Card payment processing via SIMORede | Adapter |
| Bank | Traditional banking operations | Adapter |
Key Technical Decisions
| Decision | Rationale |
|---|---|
| Go | High performance, low memory footprint, strong concurrency primitives, ideal for financial middleware |
| gRPC + gRPC-Gateway | Define APIs once in Proto, get both gRPC (internal) and REST (client-facing) with zero drift |
| GORM multi-dialect | SQLite for development speed, PostgreSQL for production reliability, same codebase |
| BLNK as core banking | Battle-tested double-entry ledger — avoids building financial accounting from scratch |
| Minio (self-hosted) | Full data sovereignty for sensitive identity documents within partner infrastructure |
| Adapter pattern | New payment providers can be added without modifying the instruction engine |
| License-based auth | Authorizes the deployment itself; per-user auth planned for multi-tenant scenarios |
Project Structure
katembed-server/
├── cmd/ # CLI entry points
│ ├── kuloffice/ # Main API server
│ ├── kuloffice-license/ # License management tool
│ ├── kuloffice-migrate/ # Database migration tool
│ └── kuloffice-bootstrap/# System bootstrap
├── config/ # Configuration files (YAML)
├── deploy/ # Kubernetes/Kustomize configs
├── docker/ # Docker Compose files
├── internal/ # Core business logic (private)
│ ├── adapter/ # Payment adapter implementations
│ ├── customer/ # Customer service
│ ├── kyc/ # KYC service
│ ├── instruction/ # Transaction instruction engine
│ ├── interceptors/ # gRPC middleware
│ ├── model/ # Database models & migrations
│ └── ... # Other service packages
├── pkg/ # Shared packages (public)
│ ├── cache/ # Caching utilities
│ ├── crypto/ # Encryption utilities
│ ├── database/ # Database connection management
│ ├── logger/ # Logging utilities
│ └── ...
├── proto/ # Protocol Buffer definitions
│ └── kuloffice/v1/ # v1 API definitions
└── tests/ # Integration tests