Code Style & Conventions

Naming Conventions

Files and Directories

Routes: Use kebab-case for route files: user-profiles/routes.ts
Services: Use PascalCase for service files: UserProfileService.ts
Directories: Use kebab-case: user-api/, merchant-profiles/
API Endpoints: Use kebab-case in URLs: /user-profiles/, /merchant-settings/

Code Elements

Classes: PascalCase - UserService, ProductCatalogService
Methods: camelCase - getUserProfile(), createProduct()
Variables: camelCase - userId, productData, isAuthenticated
Constants: UPPER_SNAKE_CASE - DATABASE_URL, JWT_SECRET
Interfaces/Types: PascalCase - DBConnection, ApiRequest

Database Schema

Tables: snake_case - user_profiles, product_categories
Columns: snake_case - user_id, created_at, merchant_id
Multi-tenancy: Always include shop_id or merchant_id

Import Organization

Organize imports in the following order with blank lines between groups:

// 1. Standard library imports
import { Router } from "express";
import { body as checkBody } from "express-validator";

// 2. Core modules (using 'core' alias)
import APIService from "core/base/service";
import { DBConnection, ID } from "core/types";
import { authenticateUser } from "core/auth/middlewares";

// 3. Shared libraries (using 'lib' alias)
import { CustomError } from "lib/errors/custom_error";
import kv from "lib/connectors/redis";

// 4. Local modules (relative imports)
import SomeService from "./service";
import { validateInput } from "../utils/validation";

Module Structure

Service Class Pattern

All service classes must extend APIService and follow this pattern:

import APIService from "core/base/service";
import { DBConnection, ID } from "core/types";

export default class ModuleService extends APIService {
  constructor(db: DBConnection) {
    super(db, "table_name");
  }

  async list(filters = {}, pagination = {}) {
    return await this.findForList(filters, pagination);
  }

  async detail(id: ID) {
    return await this.findOneOrThrow(id);
  }

  async create(data: any) {
    // Validation logic
    return await this.create(data);
  }
}

Route Handler Pattern

Route files must export a function that accepts DBConnection:

import { Router } from "express";
import { body as checkBody } from "express-validator";
import ModuleService from "./service";
import { DBConnection } from "core/types";

export default (db: DBConnection) => {
  const routes: any = Router();
  const service = new ModuleService(db);

  routes.get(
    "/list",
    service.handleOk(
      async (req) =>
        await service.list(req.query, {
          page: parseInt(req.query.page as string) || 1,
          limit: parseInt(req.query.limit as string) || 50
        })
    )
  );

  return routes;
};

Error Handling

Custom Error Usage

Always use CustomError from the shared library:

import { CustomError } from "lib/errors/custom_error";

// In service methods
if (!user) {
  throw new CustomError("USER_NOT_FOUND", "User not found with given ID", {
    userId: id
  });
}

if (!req.currentUser.is_super) {
  throw new CustomError("FORBIDDEN", "Super admin access required");
}

Response Handling

Use the service.handleOk() pattern for consistent responses:

routes.post(
  "/create",
  [checkBody("name").notEmpty()],
  service.handleOk(async (req) => {
    const result = await service.create(req.body);
    return { message: "Created successfully", data: result };
  })
);

Database Access

Multi-tenancy Pattern

Always filter by merchant/shop ID for data isolation:

async getUsersByShop(shopId: ID) {
  return await this.connector.db("users")
    .where("shop_id", shopId)
    .select("*");
}

async createProduct(data: any, merchantId: ID) {
  return await this.connector.db("products")
    .insert({
      ...data,
      shop_id: merchantId,
      created_at: new Date()
    });
}

Query Patterns

Use Knex.js patterns consistently:

// List with pagination
async findForList(filters = {}, pagination = { page: 1, limit: 50 }) {
  const query = this.connector.db(this.tableName);

  // Apply filters
  if (filters.status) {
    query.where("status", filters.status);
  }

  // Apply pagination
  const offset = (pagination.page - 1) * pagination.limit;
  query.offset(offset).limit(pagination.limit);

  return await query;
}

Authentication & Authorization

Request Context Usage

Access user context from authenticated requests:

routes.get(
  "/profile",
  service.handleOk(async (req) => {
    // User data available after authentication
    const userId = req.currentUser.id;
    const merchantId = req.merchant_id;

    return await service.getUserProfile(userId, merchantId);
  })
);

Role-based Access

Check permissions using user context:

// Check super admin status
if (!req.currentUser.is_super) {
  throw new CustomError("FORBIDDEN", "Super admin required");
}

// Check specific roles
const hasPermission = req.currentUser.roles.includes("merchant_manager");
if (!hasPermission) {
  throw new CustomError("FORBIDDEN", "Insufficient permissions");
}

Event Publishing

Domain Events

Publish events for important domain actions:

async createOrder(orderData: any) {
  const order = await this.create(orderData);

  // Publish domain event
  await this.publishEvent("order.created", {
    orderId: order.id,
    merchantId: order.merchant_id,
    amount: order.total,
    timestamp: new Date()
  });

  return order;
}

TypeScript Usage

Type Safety

Use proper typing throughout:

import { ID, ApiRequest } from "core/types";

interface CreateProductRequest {
  name: string;
  price: number;
  category_id: ID;
  merchant_id: ID;
}

async createProduct(data: CreateProductRequest): Promise<Product> {
  return await this.create(data);
}

Path Aliases

Use configured path aliases for imports:

// Use 'core' alias for @core modules
import APIService from "core/base/service";
import { DBConnection } from "core/types";

// Use 'lib' alias for lib modules
import { CustomError } from "lib/errors/custom_error";
import kv from "lib/connectors/redis";

Get Started

Architecture

Development Guide

Essentials

Code Style & Conventions

Naming Conventions

Files and Directories

Code Elements

Database Schema

Import Organization

Module Structure

Service Class Pattern

Route Handler Pattern

Error Handling

Custom Error Usage

Response Handling

Database Access

Multi-tenancy Pattern

Query Patterns

Authentication & Authorization

Request Context Usage

Role-based Access

Event Publishing

Domain Events

TypeScript Usage

Type Safety

Path Aliases

​Naming Conventions

​Files and Directories

​Code Elements

​Database Schema

​Import Organization

​Module Structure

​Service Class Pattern

​Route Handler Pattern

​Error Handling

​Custom Error Usage

​Response Handling

​Database Access

​Multi-tenancy Pattern

​Query Patterns

​Authentication & Authorization

​Request Context Usage

​Role-based Access

​Event Publishing

​Domain Events

​TypeScript Usage

​Type Safety

​Path Aliases

Naming Conventions

Files and Directories

Code Elements

Database Schema

Import Organization

Module Structure

Service Class Pattern

Route Handler Pattern

Error Handling

Custom Error Usage

Response Handling

Database Access

Multi-tenancy Pattern

Query Patterns

Authentication & Authorization

Request Context Usage

Role-based Access

Event Publishing

Domain Events

TypeScript Usage

Type Safety

Path Aliases