Development Setup

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

Clone the repository:

git clone https://github.com/zochil/api.git
cd api

Install dependencies:

npm install

Set up the database:

# Run migrations
npm run migrate

# Seed the database (optional)
npm run seed

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

# Compile TypeScript to dist/
npm run build

# No test framework configured - check individual modules for testing
# ESLint available but no scripts defined

# Install Bruno CLI
npm install -g @usebruno/cli

# Run API tests for monitoring services
bru run spec/general-monitoring

# Run marketplace monitoring tests
bru run spec/marketplace-monitoring

# Run individual test collections
bru run spec/monitoring/

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

Database Connection 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

Redis Connection Issues

Ensure Redis is running on the correct port - Check your REDIS_URL environment variable - Verify Redis is accessible from your application

Port Already in Use

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

Get Started

Architecture

Development Guide

Essentials

Prerequisites

Environment Variables

Installation

Development Commands

Project Structure

Service Architecture

Testing API Endpoints

Service Modes

Single Service Mode

Aggregated Mode (Development)

Worker Mode

Debugging

Common Issues

Next Steps

Architecture Overview

Code Style Guide

API Testing

Authentication

​Prerequisites

​Environment Variables

​Installation

​Development Commands

​Project Structure

​Service Architecture

​Testing API Endpoints

​Service Modes

​Single Service Mode

​Aggregated Mode (Development)

​Worker Mode

​Debugging

​Common Issues

​Next Steps

Architecture Overview

Code Style Guide

API Testing

Authentication

Prerequisites

Environment Variables

Installation

Development Commands

Project Structure

Service Architecture

Testing API Endpoints

Service Modes

Single Service Mode

Aggregated Mode (Development)

Worker Mode

Debugging

Common Issues

Next Steps