System Architecture
Understanding the high-level architecture of the Evolve Payments Platform - how components interact, data flows, and the overall system design.
System Type: Multi-Tenant B2B Marketplace
The Evolve Payments Platform is a Django-based multi-tenant system that facilitates commission-based sales between software vendors and resellers in African markets.
System Layers
| Layer |
Components |
Description |
| Client Layer |
Admin Portal, Business Portal, Reseller Portal |
User interfaces for different user types |
| API Gateway |
REST API Endpoints |
Centralized API access point |
| Application Layer |
Admin Module, Business Module, Reseller Module |
Core business logic and processing |
| Integration Layer |
Email, SMS, Payment Gateway (Pesapal) |
External service integrations |
| Data Layer |
SQLite (Development), PostgreSQL (Production) |
Data persistence and storage |
Core Modules Architecture
Admin Module
Purpose: Platform management and oversight for Lixnet (platform owner)
| Component |
Responsibility |
Key Features |
| User Management |
Manage all system users |
User approval, role assignment, profile management |
| Vendor Management |
Approve and manage vendors |
Vendor verification, product approval, status management |
| Transaction Oversight |
Monitor all platform transactions |
Payment tracking, commission oversight, financial reporting |
| Platform Analytics |
System-wide reporting and insights |
User metrics, revenue tracking, performance dashboards |
Business Module
Purpose: End customer management and software access
| Component |
Responsibility |
Key Features |
| Account Management |
Business customer profiles |
Company profiles, subscription management, billing |
| Software Access |
Access to purchased software |
ERP access, SACCO systems, Payroll software |
| Subscription Management |
Handle subscription lifecycle |
Plan upgrades, renewals, usage tracking |
| Support Integration |
Customer support and tickets |
Help desk, issue tracking, documentation access |
Reseller Module
Purpose: Sales agent management and commission tracking
| Component |
Description |
Sub-components |
| Profile Management |
Reseller registration and verification |
Registration & KYC, Profile Verification, Tier Management |
| Earnings Submodule |
Commission calculation and payout processing |
Commission Calculation, Payout Management, Invoice Generation, Tax Handling |
| Performance Tracking |
Sales metrics and analytics |
Sales Metrics, Conversion Rates, Leaderboards |
| Marketing Tools |
Referral and campaign management |
Referral Links, Marketing Materials, Campaign Tracking |
Special Architecture: The Reseller module includes a dedicated earnings/ submodule with its own models, services, and API structure due to the complexity of commission calculations.
Data Architecture
Database Design Patterns
| Model Category |
Models |
Purpose |
| User Models |
Admin Users, Business Users, Reseller Users |
Django Auth Extension for different user types |
| Financial Models |
Commissions, Payouts, Invoices, Transactions |
Financial data and commission tracking |
| Product Models |
Software Products, Pricing Plans, Subscriptions |
Product catalog and subscription management |
| Relationship Models |
Referrals, Sales Tracking, User Associations |
Linking users, sales, and referrals |
Key Design Principles:
- Multi-tenancy: Data isolation between different user types
- Audit Trail: All financial transactions are fully logged
- Soft Deletes: Critical data is never permanently deleted
- Timestamping: All models include created/updated timestamps
API Architecture
RESTful API Design
Each module exposes a versioned REST API following consistent patterns.
| API Module |
Base Path |
Endpoints |
Purpose |
| Admin API |
/api/v1/admin/ |
users/, vendors/, transactions/, analytics/ |
User management, vendor approval, financial oversight, platform metrics |
| Business API |
/api/v1/business/ |
profile/, subscriptions/, software/, support/ |
Business profiles, subscription management, software access, support tickets |
| Reseller API |
/api/v1/reseller/ |
profile/, earnings/, referrals/, performance/ |
Reseller profiles, commission data, referral tracking, sales metrics |
API Standards:
| Aspect |
Standard |
Example |
| Authentication |
Token-based |
Authorization: Token abc123 |
| Content Type |
JSON |
Content-Type: application/json |
| Error Format |
Standardized |
{"error": "message", "code": 400} |
| Pagination |
Cursor-based |
?cursor=abc&limit=20 |
Integration Architecture
External Service Integrations
| Service |
Purpose |
Integration Pattern |
Fallback Strategy |
| Pesapal |
Payment processing |
REST API + Webhooks |
Manual payment verification |
| SMSLeopard |
SMS notifications |
REST API |
Email notifications |
| SMTP |
Email notifications |
Direct SMTP |
Console logging (dev) |
Integration Pattern: All external integrations are wrapped in service classes with proper error handling and fallback mechanisms.
Security Architecture
Security Layers
| Security Layer |
Components |
Implementation |
| Authentication Layer |
Django Authentication, Token-based API Auth, Two-Factor Authentication |
User identity verification and session management |
| Authorization Layer |
Role-based Permissions, Module-level Access Control, API Endpoint Protection |
Access control based on user roles and permissions |
| Data Protection |
Environment Variables, Database Encryption, PII Data Handling |
Sensitive data encryption and secure storage |
| Transport Security |
HTTPS Enforcement, CSRF Protection, XSS Prevention |
Secure data transmission and web security |
Key Security Features:
- Environment-based Configuration: Sensitive data in .env files
- Role-based Access: Admin, Business, Reseller role separation
- API Rate Limiting: Prevent abuse and ensure fair usage
- Audit Logging: All critical actions are logged
Deployment Architecture
Environment Strategy
| Environment |
Purpose |
Database |
Deployment Method |
| Development |
Local development |
SQLite |
manage.py runserver |
| Staging |
Testing & QA |
PostgreSQL |
Docker + CI/CD |
| Production |
Live system |
PostgreSQL |
Docker + Orchestration |
Clean Architecture Implementation
Layer Separation
Each module follows clean architecture principles with clear separation of concerns:
| Architecture Layer |
Components |
Responsibility |
| Presentation Layer |
API Controllers, Web Controllers, Serializers, Form Handlers |
User interface and API endpoint handling |
| Application Layer |
Business Logic, Use Cases, Workflows, Orchestration |
Application-specific business rules and workflows |
| Domain Layer |
Business Entities, Value Objects, Business Rules, Domain Events |
Core business logic and domain models |
| Infrastructure Layer |
Data Access, External APIs, File System, Third-party Services |
External system integration and data persistence |
Benefits of This Architecture:
- Testability: Each layer can be tested independently
- Maintainability: Clear separation makes changes easier
- Scalability: Components can be scaled independently
- Flexibility: Easy to swap implementations
Performance Architecture
Performance Strategies
| Area |
Strategy |
Implementation |
| Database |
Query Optimization |
Repository pattern, select_related, prefetch_related |
| API |
Response Caching |
Django cache framework, Redis (planned) |
| Static Files |
CDN Delivery |
Static file optimization, compression |
| Background Tasks |
Async Processing |
Celery (planned), email queues |
Future Architecture Evolution
Planned Enhancements
Roadmap Items: These are planned improvements to the current architecture.
- Microservices Migration: Break down monolith into independent services
- Event-Driven Architecture: Implement domain events for better decoupling
- Caching Layer: Redis for session management and API caching
- Message Queues: Async processing for emails and notifications
- API Gateway: Centralized API management and rate limiting
- Container Orchestration: Kubernetes for production deployments
Architecture Benefits: This clean, modular architecture provides a solid foundation that can scale with business growth while maintaining code quality and developer productivity.