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

# Development Setup

> Set up your local development environment for the Zochil API

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

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

```bash theme={null}
git clone https://github.com/zochil/api.git
cd api
```

2. Install dependencies:

```bash theme={null}
npm install
```

3. Set up the database:

```bash theme={null}
# Run migrations
npm run migrate

# Seed the database (optional)
npm run seed
```

4. Start the development server:

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

## Development Commands

<CodeGroup>
  ```bash Development Server theme={null}
  # 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
  ```

  ```bash Build Commands theme={null}
  # Compile TypeScript to dist/
  npm run build

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

  ```bash API Testing with Bruno theme={null}
  # 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/
  ```
</CodeGroup>

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

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

```bash theme={null}
# Run only user-api service
SERVICE_NAME=user-api npm run dev
```

### Aggregated Mode (Development)

```bash theme={null}
# Run all services in one process
npm run dev
```

### Worker Mode

```bash theme={null}
# Enable background job processing
WORKER_SERVICE=true npm run dev
```

## Debugging

Enable debug logging by setting the `DEBUG` environment variable:

```bash theme={null}
DEBUG=zochil:* npm run dev
```

## Common Issues

<AccordionGroup>
  <Accordion title="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
  </Accordion>

  {" "}

  <Accordion title="Redis Connection Issues">
    * Ensure Redis is running on the correct port - Check your `REDIS_URL`
      environment variable - Verify Redis is accessible from your application
  </Accordion>

  <Accordion title="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
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture Overview" icon="server" href="/architecture/overview">
    Learn about our platform architecture
  </Card>

  <Card title="Code Style Guide" icon="code" href="/guide/code-style">
    Follow our coding conventions
  </Card>

  <Card title="API Testing" icon="test-tube" href="/guide/testing">
    Test APIs with Bruno collections
  </Card>

  <Card title="Authentication" icon="shield" href="/essentials/authentication">
    Implement authentication in your app
  </Card>
</CardGroup>