> ## Documentation Index
> Fetch the complete documentation index at: https://docs-kfhye.zochil.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Microservices Architecture

> Overview of individual services and their responsibilities

## 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:

```typescript theme={null}
// 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**:

```bash theme={null}
SERVICE_NAME=user-api npm run dev
```

Loads only `api/user-api/server.ts`

**Aggregated Mode**:

```bash theme={null}
npm run dev
```

Loads all services in development

**Worker Mode**:

```bash theme={null}
WORKER_SERVICE=true npm run dev
```

Enables Dapr pub/sub endpoints

### Service Bootstrap Pattern

Each service follows the same bootstrap pattern:

```typescript theme={null}
// 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:

```typescript theme={null}
// 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