Skip to main content

​
Service Overview

The Zochil API is organized into domain-specific microservices, each handling specific business capabilities. Each service can be deployed independently or run together in development mode.

​
Core Services

​
Admin API (admin-api/)

Merchant management and business operations Handles merchant-related features including:
  • Storefront settings and customization
  • Content management (posts, banners)
  • Product catalog and inventory
  • Payment configuration
  • Order management for merchants
  • Customer relationship management
Key modules: Products, Orders, Customers, Settings, Payments, Content

​
User API (user-api/)

Authentication and user management Manages user accounts and authentication for:
  • Buyer registration and profiles
  • Merchant admin accounts
  • Device management and sessions
  • Authentication tokens and security
  • User roles and permissions
Key modules: Accounts, Authentication, Devices, Profiles, Roles

​
Storefront API (storefront-api/)

Public-facing e-commerce functionality Powers the customer-facing storefront with:
  • Product catalog browsing
  • Business information display
  • Banner and content delivery
  • Shopping cart functionality
  • Order placement for buyers
Key modules: Catalog, Cart, Content, Business Info, Public APIs

​
Order API (order-api/)

Order lifecycle management Handles order processing for both merchants and customers:
  • Order placement and validation
  • Payment processing integration
  • Order status tracking
  • Settlement and fulfillment
  • Cart management
Key modules: Orders, Carts, Payments, Settlements, Fulfillment

​
Catalog API (catalog-api/)

Product and inventory management Manages product information and inventory:
  • Product catalogs and variants
  • Category and brand management
  • Inventory tracking
  • Price management
  • Product search and filtering
Key modules: Products, Categories, Brands, Inventory, Search

​
Monitoring API (monitoring-api/)

Super admin oversight and analytics Provides administrative oversight with:
  • System monitoring and health checks
  • Merchant account management
  • Analytics and reporting
  • Platform administration
  • Marketplace builder tools
Key modules: Monitoring, Analytics, Admin Tools, Marketplace Builder

​
Analytics API (analytics-api/)

Data analytics and reporting Handles analytics and business intelligence:
  • Sales analytics and reporting
  • User behavior tracking
  • Performance metrics
  • Business intelligence dashboards
Key modules: Analytics, Reports, Metrics, Dashboards

​
Job API (job-api/)

Background processing Manages asynchronous tasks and background jobs:
  • Email and SMS notifications
  • Data processing tasks
  • Scheduled operations
  • Event handling
  • Integration workflows
Key modules: Jobs, Notifications, Schedulers, Workers

​
Driver API (driver-api/)

Delivery and logistics Handles delivery operations:
  • Delivery company integration
  • Order fulfillment tracking
  • Driver management
  • Logistics coordination
Key modules: Delivery, Companies, Orders, Tracking

​
Marketplace API (marketplace-api/)

Multi-vendor marketplace features Supports marketplace functionality:
  • Multi-vendor operations
  • Commission management
  • Vendor onboarding
  • Marketplace analytics
Key modules: Vendors, Commissions, Analytics, Operations

​
Service Communication

​
Direct API Calls

Services communicate through HTTP API calls when real-time data is needed.

​
Event-driven Architecture

Services publish and subscribe to domain events via Dapr pub/sub: 
// Publishing events
await this.publishEvent("order.created", {
  orderId: order.id,
  merchantId: order.merchant_id,
  amount: order.total
});

// Worker subscriptions
export const PUBSUB_SUBSCRIPTIONS = [
  {
    route: "/worker/order/fulfillment",
    pubsubname: process.env.DAPR_PUBSUB_NAME,
    topic: "order.created"
  }
];

​
Shared Libraries

Common functionality is shared through the lib/ directory:
  • Database connectors
  • External API integrations
  • Utility functions
  • Error handling
  • Authentication helpers

​
Service Configuration

​
Environment-based Service Loading

Single Service Mode: 
SERVICE_NAME=user-api npm run dev
Loads only api/user-api/server.ts Aggregated Mode: 
npm run dev
Loads all services in development Worker Mode: 
WORKER_SERVICE=true npm run dev
Enables Dapr pub/sub endpoints

​
Service Bootstrap Pattern

Each service follows the same bootstrap pattern: 
// server.ts
import kv from "lib/connectors/redis";
import { db } from "lib/connectors/knex";
import { startAPIService } from "lib/api/service";
import { createAPIRouter } from "./router";

const router = createAPIRouter({ db, kv });
startAPIService(router);

​
Router Configuration

Each service has a router.ts that aggregates all module routes: 
// router.ts
import { Router } from "express";
import moduleRoutes from "./module/routes";
import { DBConnection } from "core/types";

export function createAPIRouter(connectors: DBConnection) {
  const router: any = Router();
  router.use("/module-path", moduleRoutes(connectors));
  return router;
}

​
Service Dependencies

​
Required Dependencies

  • Database: PostgreSQL connection via Knex.js
  • Cache: Redis connection for sessions and caching
  • Environment: Configuration via environment variables

​
Optional Dependencies

  • Event Bus: Dapr pub/sub for event-driven communication
  • External APIs: Various integrations (payment, SMS, email)
  • File Storage: Cloud storage for media files

​
Deployment Considerations

​
Independent Deployment

Each service can be deployed independently with:
  • Own database connections
  • Separate scaling policies
  • Individual monitoring and logging
  • Service-specific configuration

​
Shared Resources

Services share:
  • PostgreSQL database (with multi-tenant isolation)
  • Redis cache
  • Event bus infrastructure
  • External service credentials