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

# Architecture Overview

> Understanding the Zochil Platform architecture and design principles

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

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

### Aggregated Mode (Development)

Run all services in one process:

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

### Worker Mode

Enable background job processing:

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