Cendika Communication Platform

🚀 Africa-First Communication API Platform

Cendika is an open-source, production-ready communication API platform built following Sendexa documentation and standards. Designed with Africa in mind, it provides unified APIs for SMS, Voice, Email, WhatsApp, Push Notifications, and Phone Lookup services with African-specific optimizations.

💝 Support Cendika

Cendika is open source and free forever. Your support helps:

For Donors:

• $10/month: Supports hosting for documentation
• $50/month: Covers CI/CD and testing infrastructure
• $100/month: Funds African developer internships
• $500/month: Sponsors new African country coverage

For Companies:

• Sponsor a Feature: Fund specific African integrations
• Enterprise Support: Get priority support and custom features
• Become a Partner: Joint go-to-market for African markets

Ways to support:

• GitHub Sponsors
• Open Collective
• Direct partnerships
• Resource contributions (servers, SMS credits)

✨ Features

📱 Multi-Channel Communication

• SMS API with African provider routing (MTN, Vodacom, Orange, Telecel, etc.)
• Voice API with IVR support for African phone systems
• Email API with African SMTP optimizations
• WhatsApp Business API integration
• Push Notifications for web and mobile
• Two-way SMS for customer engagement

🌍 Africa-First Features

• Phone Lookup Service - Carrier detection, MNP (Mobile Number Portability), validation
• Local Pricing - Country-specific pricing for 54 African nations
• Network Routing - Intelligent routing to best local providers
• African SMS Optimizations - Character encoding, delivery optimization
• Local Payment Integration - Paystack, Flutterwave, mobile money support

🔧 Developer Experience

• Unified API - Single endpoint for all communication channels
• TypeScript First - Full type safety from database to API responses
• OpenAPI/Swagger - Auto-generated API documentation
• Webhook Support - Real-time delivery reports and events
• Rate Limiting - Per-API key and per-service rate limits
• Bulk Operations - Send to millions with queue management

💼 Business Features

• Multi-tenant Architecture - Support for personal and business accounts
• Team Collaboration - Role-based access control
• Usage Analytics - Real-time dashboards and reports
• Credit System - Flexible prepaid billing
• Invoice Generation - Automated billing with PDF generation
• Audit Logs - Complete audit trail for compliance

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                 API Gateway (Hono)                  │
├─────────────────────────────────────────────────────┤
│    Authentication  │  Rate Limiting  │  Validation  │
├─────────────────────────────────────────────────────┤
│              Service Layer (Modules)                │
│  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐        │
│  │ SMS │  │Voice│  │Email│  │Push │  │Whats│        │
│  └─────┘  └─────┘  └─────┘  └─────┘  └─────┘        │
├─────────────────────────────────────────────────────┤
│            Provider Layer (Africa-First)            │
│  ┌─────────┐  ┌─────────┐  ┌──────────────┐         │
│  │African  │  │Payment  │  │Local SMTP    │         │
│  │SMS      │  │Gateways │  │Services      │         │
│  └─────────┘  └─────────┘  └──────────────┘         │
├─────────────────────────────────────────────────────┤
│              Data Layer (Prisma/PostgreSQL)         │
└─────────────────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Bun (v1.0.0 or higher) - Installation Guide
• PostgreSQL (v14 or higher)
• Redis (v7 or higher) - For caching and queues
• Docker (optional) - For containerized deployment

Installation

# Clone the repository
git clone https://github.com/CollinsVidzro/cendika.git
cd cendika

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your configuration

# Set up Africa-specific configuration
cp .env.example .env.africa
# Edit .env.africa with African providers

# Set up database
bun run db:generate
bun run db:migrate
bun run db:seed

# Start development server
bun run dev

Docker Deployment

# Start all services
docker-compose up -d

# View logs
docker-compose logs -f

# Run database migrations
docker-compose exec api bun run db:migrate

# Seed African data
docker-compose exec api bun run db:seed

📚 API Documentation

Once running, access the interactive API documentation:

• Swagger UI: http://localhost:3000/docs
• ReDoc: http://localhost:3000/redoc
• API Health: http://localhost:3000/api/v1/health

Authentication

Cendika uses API key authentication:

# Generate an API key
curl -X POST http://localhost:3000/api/v1/auth/api-keys \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "permissions": ["sms:send", "sms:read"]
  }'

# Use the API key
curl -X GET http://localhost:3000/api/v1/sms \
  -H "X-API-Key: sk_live_..."

Send Your First SMS

curl -X POST http://localhost:3000/api/v1/sms/send \
  -H "X-API-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+233501234567",
    "content": "Welcome to Cendika! Your verification code is 123456",
    "senderId": "Cendika"
  }'

Lookup Phone Number (Africa-Specific)

curl -X GET "http://localhost:3000/api/v1/lookup/number/+233501234567" \
  -H "X-API-Key: sk_live_..."

🏗️ Project Structure

src/
├── app/                    # Application setup and routing
├── modules/               # Feature modules
│   ├── auth/             # API key authentication
│   ├── sms/              # SMS service with African routing
│   ├── voice/            # Voice calls and IVR
│   ├── email/            # Email service (self-built)
│   ├── lookup/           # Africa phone lookup
│   ├── verify/           # OTP and verification
│   ├── push/             # Push notifications
│   ├── whatsapp/         # WhatsApp integration
│   └── billing/          # Africa-focused billing
├── core/                 # Core infrastructure
│   ├── config/           # Configuration management
│   ├── providers/        # External provider integrations
│   ├── services/         # Self-built core services
│   ├── utils/            # Utilities and helpers
│   └── constants/        # Constants and enums
├── templates/            # Email and SMS templates
└── webhooks/             # Webhook handlers

🌍 Africa Coverage

Cendika supports all 54 African countries with:

SMS Coverage

• West Africa: Ghana, Nigeria, Ivory Coast, Senegal
• East Africa: Kenya, Tanzania, Uganda, Rwanda
• Southern Africa: South Africa, Zambia, Zimbabwe
• North Africa: Egypt, Morocco, Algeria, Tunisia

Network Support

• MTN Group: Ghana, Nigeria, Rwanda, Uganda, Zambia
• Vodacom Group: South Africa, Tanzania, DRC, Mozambique
• Orange Group: Ivory Coast, Senegal, Cameroon, Mali
• Airtel Africa: Kenya, Nigeria, Tanzania, Uganda
• Telecel Group: Ghana, Burkina Faso, Niger

Pricing

Country-specific pricing in local currencies (GHS, NGN, KES, ZAR, etc.) with volume discounts.

🔌 Integrations

SMS Providers

• Telecel
• MTN
• Vodacom
• Orange

Payment Gateways

• Paystack (Nigeria, Ghana, Kenya, South Africa)
• Flutterwave (across Africa)
• Stripe (international)
• Mobile Money (M-Pesa, MTN MoMo, Airtel Money)

Storage

• Amazon S3
• Local file system
• DigitalOcean Spaces

Queue & Cache

• Redis (Bull queues)
• In-memory cache (development)

🧪 Testing

# Run all tests
bun test

# Run unit tests
bun test:unit

# Run integration tests
bun test:integration

# Run e2e tests
bun test:e2e

# Run tests with coverage
bun test --coverage

📈 Monitoring & Observability

• Health checks: /api/v1/health
• Metrics: Prometheus metrics at /metrics
• Logging: Structured JSON logging
• Tracing: Distributed tracing support
• Alerting: Webhook-based alerting

🔐 Security

• API Key Authentication with prefix/secret
• Rate Limiting per API key and IP
• Input Validation with Zod schemas
• SQL Injection Protection via Prisma
• CORS Configuration for web clients
• HTTPS Enforcement in production
• Audit Logging for all operations

📊 Performance

• Horizontal Scaling - Stateless API servers
• Database Connection Pooling
• Redis Caching for frequent queries
• Background Job Processing with Bull
• CDN Integration for static assets
• Load Balancing ready

🚢 Deployment

Environment Variables

Variable	Required	Description	Example
DATABASE_URL	Yes	PostgreSQL connection URL	postgresql://user:pass@localhost:5432/cendika
REDIS_URL	Yes	Redis connection URL	redis://localhost:6379
PORT	No	API server port	3000
NODE_ENV	No	Environment	production
LOG_LEVEL	No	Logging level	info
API_RATE_LIMIT_WINDOW	No	Rate limit window (ms)	60000
API_RATE_LIMIT_MAX	No	Max requests per window	100
JWT_SECRET	Yes	JWT signing secret	your-secret-key

Production Deployment

# Build the application
bun run build

# Start in production mode
NODE_ENV=production bun start

# Or using PM2
pm2 start dist/index.js --name cendika-api

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Workflow

# Install dependencies
bun install

# Generate Prisma client
bun run db:generate

# Run database migrations
bun run db:migrate

# Start development server with hot reload
bun run dev

# Run linter
bun run lint

# Format code
bun run format

# Run type checking
bun run typecheck

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Sendexa - For the API specifications and inspiration
• Bun - For the incredible JavaScript runtime
• Prisma - For the amazing database toolkit
• All Contributors - Who help make this project better

📞 Support

• Documentation: docs.cendika.dev
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

🚧 Roadmap

See our ROADMAP.md for upcoming features and improvements.

---

Built with ❤️ for Africa by the open-source community

---