Skip to main content

​
Platform Architecture

Zochil Platform is built as a multi-tenant e-commerce system that enables merchants to create and manage their online businesses. The platform uses a microservices architecture with clear separation of concerns across different business domains.

​
Multi-tenancy

When merchants register using our mobile and web apps, the system creates a merchant record in the database and generates a unique merchant ID. All entities include this merchant ID in their records to ensure data isolation. We have a multi-tenant NextJS e-commerce storefront website that handles merchant subdomains or custom domains. Buyers can view product catalogs, posts, banners, and promotions, and place orders through our multi-tenant storefront.

​
Core Components

​
Database Layer

  • PostgreSQL: Primary data storage with Knex.js query builder
  • Redis: Session management, caching, and real-time data
  • Multi-tenancy: All tables include shop_id/merchant_id for data isolation

​
API Services

  • Express.js: RESTful API services built with TypeScript
  • JWT Authentication: Token-based authentication with Redis storage
  • Request Validation: Express-validator for input validation
  • Error Handling: Custom error classes with structured responses

​
Event System

  • Dapr Pub/Sub: Event-driven architecture for real-time updates
  • Background Jobs: Job processing with worker services
  • Domain Events: Services publish events via this.publishEvent()

​
Service Architecture

Each microservice follows a consistent pattern: 
service-api/
├── domain/
│   ├── routes.ts         # Route handlers and validation
│   └── service.ts        # Business logic and data access
├── router.ts             # Service-level routing
└── server.ts            # Service bootstrap and configuration

​
Service Structure

  • Routes: Express Router with route definitions, validation, and middleware
  • Services: Business logic classes extending APIService base class
  • Database: Knex.js database connections passed via dependency injection
  • Authentication: Middleware-based authentication with user context

​
Deployment Modes

​
Single-service Mode

Run individual services in isolation: 
SERVICE_NAME=user-api npm run dev

​
Aggregated Mode (Development)

Run all services in one process: 
npm run dev

​
Worker Mode

Enable background job processing: 
WORKER_SERVICE=true npm run dev

​
Data Flow

  1. Client Request: HTTP request to API endpoint
  2. Authentication: JWT token validation and user context setup
  3. Route Handler: Express route with validation middleware
  4. Service Layer: Business logic execution
  5. Database: Data persistence with multi-tenant filtering
  6. Response: Structured JSON response
  7. Events (Optional): Domain events published to event bus

​
Security Model

  • JWT Tokens: Stored in Redis with device association
  • Role-based Access: req.currentUser.roles and req.currentUser.is_super
  • Multi-tenant Isolation: Automatic filtering by merchant ID
  • Input Validation: Express-validator on all endpoints
  • Custom Errors: Structured error responses with metadata