Skip to main content

​
Prerequisites

Before you begin, ensure you have the following installed:
  • Node.js (v16 or higher)
  • npm or yarn
  • PostgreSQL (v12 or higher)
  • Redis (v6 or higher)
  • Docker (optional, for containerized development)

​
Environment Variables

Create a .env file in the root directory with the following required variables: 
# Required Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/zochil_dev
DATABASE_CA_FILE=/path/to/ca-certificate.crt
REDIS_URL=redis://localhost:6379
PORT=3000

# Service Configuration
SERVICE_NAME=user-api     # Optional: run single service mode
WORKER_SERVICE=true       # Optional: enable Dapr pub/sub endpoints
NODE_ENV=development

# Authentication
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=24h

# External Services (optional)
MAILGUN_API_KEY=your-mailgun-api-key
AWS_ACCESS_KEY_ID=your-aws-access-key
AWS_SECRET_ACCESS_KEY=your-aws-secret-key

​
Installation

  1. Clone the repository:
git clone https://github.com/zochil/api.git
cd api
  1. Install dependencies:
npm install
  1. Set up the database:
# Run migrations
npm run migrate

# Seed the database (optional)
npm run seed
  1. Start the development server:
npm run dev

​
Development Commands

# Start all services in development mode
npm run dev

# Start a specific service
SERVICE_NAME=user-api npm run dev

# Start with worker mode enabled
WORKER_SERVICE=true npm run dev

# Start production server
npm start

​
Project Structure

api/
├── api/                    # API services
│   ├── @core/             # Shared core modules
│   ├── user-api/          # User management service
│   ├── catalog-api/       # Product catalog service
│   ├── order-api/         # Order management service
│   └── ...                # Other services
├── lib/                   # Shared libraries
│   ├── connectors/        # Database connectors
│   ├── external-apis/     # External service integrations
│   └── utils/            # Utility functions
├── db/                   # Database related files
│   └── migrations/       # Database migrations
├── docs/                 # Documentation
└── spec/                 # API specifications (Bruno)

​
Service Architecture

Each service follows a consistent pattern: 
service-api/
├── domain/
│   ├── routes.ts         # Route handlers
│   └── service.ts        # Business logic
├── router.ts             # Service router
└── server.ts            # Service bootstrap

​
Testing API Endpoints

We use Bruno for API testing. The specifications are located in the spec/ directory: 
# Install Bruno CLI
npm install -g @usebruno/cli

# Run API tests
bru run spec/general-monitoring

# Run specific test collection
bru run spec/marketplace-monitoring

​
Service Modes

The API supports different deployment modes:

​
Single Service Mode

# Run only user-api service
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

​
Debugging

Enable debug logging by setting the DEBUG environment variable: 
DEBUG=zochil:* npm run dev

​
Common Issues

  • Ensure PostgreSQL is running on the correct port
  • Check your DATABASE_URL environment variable
  • Verify database credentials and permissions
  • Make sure the database exists
  • Ensure Redis is running on the correct port - Check your REDIS_URL environment variable - Verify Redis is accessible from your application
  • Change the PORT environment variable
  • Kill the process using the port: lsof -ti:3000 | xargs kill -9
  • Use a different port for development

​
Next Steps

Architecture Overview

Learn about our platform architecture

Code Style Guide

Follow our coding conventions

API Testing

Test APIs with Bruno collections

Authentication

Implement authentication in your app