Getting Started

This guide will help you set up the API backend for local development.

Prerequisites

• Node.js 22+
• pnpm 10+
• Docker and Docker Compose
• PostgreSQL client (optional, for debugging)

Installation

1. Clone the repository and install dependencies:

   git clone <api-repo-url>
   cd api
   pnpm install

2. Set up environment variables:

   cp .env.example .env

3. Configure your .env file with required values (see below)

Environment Variables

Key environment variables:

Variable	Description
DATABASE_URL	PostgreSQL connection string
REDIS_URL	Redis connection string
NEO4J_URI	Neo4j bolt URI
JWT_SECRET	Secret for JWT signing
STRIPE_SECRET_KEY	Stripe API key
SENDGRID_API_KEY	SendGrid API key

Starting the Database

Start PostgreSQL, Redis, and Neo4j with Docker:

pnpm services:up   # from the repo root

Running Migrations

Apply database migrations:

pnpm db:migrate

Starting the Server

Start the development server with hot reload:

pnpm dev

The API will be available at http://localhost:8080.

Verifying the Setup

1. Check the health endpoint:

   curl http://localhost:8080/health

2. View the API documentation at http://localhost:8080/reference

Running Tests

pnpm test           # Run all tests
pnpm test:watch     # Watch mode
pnpm test src/path/to/test.ts  # Single file

Troubleshooting

Database Connection Issues

Ensure Docker containers are running:

docker compose ps

Port Already in Use

Check what's using port 8080:

lsof -i :8080

Migration Errors

Try reverting and re-running:

pnpm db:revert
pnpm db:migrate