Microservices Conceptual Design

Our system is built on a modern microservisces architecture, with each service designed to handle specific business capabilities. This approach enables scalability, resilience, and maintainability.

Core Services Overview

1. Frontend Gateway Service

• Technology: Next.js API Routes / Node.js on Cloud Run
• Responsibilities:
  • Serves the Next.js frontend
  • Handles API requests from the frontend
  • Authenticates UI users (House, Agents)
  • Routes requests to appropriate backend services

2. User & Agent Management Service

• Technology: Node.js/TypeScript
• Data Store: PostgreSQL
• Responsibilities:
  • Manages user accounts (House and Agents)
  • Handles profiles and permissions
  • Generates and manages API keys
  • Credential verification

3. Device Management Service

• Technology: Node.js/TypeScript
• Data Store: PostgreSQL & Firestore
• Responsibilities:
  • Registers agent devices
  • Manages device credentials
  • Tracks device status
  • Handles device installation verification

4. Transaction Ingestion Service

• Technology: Cloud Function (Node.js)
• Responsibilities:
• Receives raw transaction data
• Performs initial validation
• Publishes to Pub/Sub topics

5. Recharge Processing Service

• Technology: Node.js/TypeScript
• Data Store: PostgreSQL
• Responsibilities:
  • Business logic validation
  • Fee calculation
  • Transaction recording
  • Notification triggering

6. Payout Orchestration Service

• Technology: Node.js/TypeScript
• Data Store: PostgreSQL
• Responsibilities:
  • Validates payout requests
  • Manages device communication
  • Tracks payout status
  • Records final transactions

7. Service Communication

• Communication Patterns Our services communicate through two primary patterns:
  • Synchronous: REST APIs for direct requests
  • Asynchronous: Pub/Sub for event-driven operations
• Event-Driven Architecture We use Google Cloud Pub/Sub for asynchronous communication between services. Key topics include:
  • new_recharge_data: Raw transaction data
  • recharge_validated: Processed transactions
  • new_payout_request: Payout requests
  • payout_status_update: Payout status changes

Data Flow Examples

Recharge Flow

Payout Flow

Service Design Principles

1. Single Responsibility

   • Each service focuses on a specific business capability
   • Clear boundaries and interfaces

2. Data Ownership

   • Services own their data
   • No direct database access from other services
   • Data replication when necessary

3. Resilience

   • Circuit breakers for external calls
   • Retry mechanisms for transient failures
   • Graceful degradation

4. Scalability

   • Independent scaling per service
   • Stateless design where possible
   • Efficient resource utilization

Security Considerations

Each service implements security at multiple levels:

1. Authentication

   • API key validation
   • JWT token verification
   • Service-to-service authentication

2. Authorization

   • Role-based access control
   • Resource-level permissions
   • Action-level restrictions

3. Data Protection

   • Encryption in transit
   • Secure credential storage
   • Input validation

Monitoring and Observability

Services expose metrics and logs for:

• Request rates and latencies
• Error rates and types
• Resource utilization
• Business metrics