Skip to content

Cubex System Architecture Documentation

This document provides a comprehensive overview of our project infrastructure, detailing our services, providers, and integrations. The goal is to help new team members understand the roles of each component, their deployment environment, and how they interconnect.

Cubex API (Cloudflare Workers)

Overview

Our API is deployed on Cloudflare Workers, a serverless platform that allows us to run lightweight, fast, and cost-effective functions at the edge of the Cloudflare network. This architecture ensures low-latency responses for end users around the globe and simplifies scaling.

Role

The API handles requests for core application functionalities, including authentication, data processing, payment processing, and interactions with third-party services.

Key Points

  • Environment Variables: Sensitive data, like API keys and secrets, are stored in Cloudflare’s environment settings.
  • Authentication: Ensure all routes requiring authentication are properly secured using Cloudflare’s security tokens.
  • Deployment: Deployments are automated via Cloudflare’s CLI (Wrangler) or its GitHub Actions integration.

Cubex Admin Portal (Vercel)

Overview

The admin portal is hosted on Vercel, a cloud platform optimized for frontend frameworks and static websites. This environment provides zero-config deployment, allowing us to quickly roll out updates.

Role

The admin interface serves as the frontend management dashboard, allowing internal team members to oversee and manage key application processes such as user activity, transaction details, and account verification.

Key Points

  • Environment Variables: Managed within Vercel’s environment settings to handle secure access to the API and other integrations.
  • Continuous Deployment: Each commit pushed to the master branch auto-deploys to production.
  • Logging: Console logs and errors are available through Vercel’s dashboard for quick diagnosis.
  • Known Issues: Continuous Deployment might fail at times due to lint errors in the code. Make sure this is fixed before pushing.

3rd Party Integrations

Resend - Transactional Email

  • Description: Resend is our transactional email provider, handling all essential email communications with users such as welcome emails, password resets, and notifications.
  • API Endpoint Integration: Used in our API layer for email delivery.
  • Configuration: Environment variables for API keys are stored in Cloudflare Workers.

Slack - Team Notifications

  • Description: Slack is used for real-time notifications, alerting our team on key events such as new sign-ups, errors, or failed transactions.
  • API Integration: Configured within the API to trigger messages on relevant Slack channels.
  • Security: Ensure webhook URLs are secure and only accessible to necessary services.

Paystack - Payment Gateway

  • Description: Paystack provides secure payment processing for our local bank transfers.
  • Usage: Integrated into our API to process one-time payments.
  • Configuration: Paystack keys and secrets are secured within the Cloudflare environment. Callback URLs are configured in Paystack’s dashboard to ensure accurate transaction tracking.

Quidax - Crypto Services

  • Description: Quidax allows us to offer cryptocurrency receive and sale features.
  • Integration: API endpoints are used for handling crypto transactions, from user wallet creation to receive/sell orders. Every user on our system has subwallet at Quidax where their assets are managed. Our API gives instruction to Quidax servers based on user interactions.
  • Configuration: API keys are secured in Cloudflare Workers, and all crypto transactions follow strict security protocols.

VTPass - Utilities Provider

  • Description: VTPass enables utility bill payments, including airtime, electricity, and other services, providing an all-in-one solution for our users.
  • Integration: API endpoints facilitate these transactions directly from our application.
  • Configuration: Secure API credentials are managed within our API’s environment settings.

Dojah - KYC Verification

  • Description: Dojah provides Know Your Customer (KYC) verification services, essential for verifying user identities for compliance. We have two levels of verification. Level 1 is done using only phone number, level 2 is done using BVN. Both of them have limits that can be set in admin dashboard feature config.
  • Integration: API endpoints within the Cloudflare Workers API handle requests to verify users’ identity documents.
  • Security: Data exchanged with Dojah follows stringent compliance measures to protect user privacy.

Klaviyo - Email Marketing

  • Description: Klaviyo powers our marketing communications, enabling us to segment and reach our users with tailored content and updates. We create a klaviyo user at user registration.
  • Integration: Used in the admin interface to trigger marketing campaigns and updates.
  • Data Management: Ensure user data used in Klaviyo follows all regulatory compliance guidelines.

Sentry - Error Logging & Tracking

  • Description: Sentry provides real-time error monitoring, helping us track and fix issues efficiently.
  • Integration: Connected to only the API to capture errors, performance issues, and alerts. It is recommended that this is extended to the Admin at some point in the future.
  • Setup: Error logs and stack traces can be reviewed in Sentry’s dashboard, which is linked to both Cloudflare and Vercel environments.

Static HTML Content (CPanel)

Overview

We use CPanel for deploying static HTML pages used by our application. This service primarily hosts privacy and contact us contents used on the mobile app. It is recommended that this is moved to cloudflare so we can end the cpanel services.

Key Points

  • Access: CPanel credentials should be securely stored and only shared with authorized personnel.
  • File Management: Static HTML and assets can be managed through CPanel’s File Manager, FTP, or direct upload via GitHub deployments.

Best Practices

  1. Error Handling
  2. Always use Sentry for error tracking
  3. Implement proper try-catch blocks

  4. Use appropriate error status codes

  5. API Security

  6. Validate all inputs
  7. Implement rate limiting

  8. Use appropriate authentication mechanisms

  9. Third-Party Services

  10. Implement proper error handling for all third-party services
  11. Use webhook validation

  12. Implement retry mechanisms for failed requests

  13. Monitoring

  14. Set up Sentry alerts
  15. Configure Slack notifications for critical events
  16. Regular monitoring of API endpoints

Support and Resources

This documentation should provide a solid foundation for new team members to understand our system architecture and begin contributing to the project.