Local Development Setup

This guide covers setting up the AIQLick development environment on your local machine.

Prerequisites

Dependency	Minimum Version	Purpose
Node.js	20+	Backend (NestJS) and frontend (Next.js)
Python	3.11+	Background tasks (FastAPI)
Docker Desktop	Latest	PostgreSQL, Redis, MinIO containers

Ensure Docker Desktop is configured to start on login so that development containers auto-restart.

Docker Services

Three infrastructure services run as Docker containers with --restart unless-stopped to survive host reboots.

Service	Container Name	Port(s)	Credentials
PostgreSQL 16 + pgvector	aiqlick-local-postgres	15432	user: aiqlick, password: aiqlick, database: aiqlick_db
Redis 7	aiqlick-local-redis	6379	No authentication
MinIO (S3-compatible)	aiqlick-local-minio	9000 (API), 9001 (console)	user: minioadmin, password: minioadmin

Starting Docker Services

# PostgreSQL with pgvector extension
docker run -d \
  --name aiqlick-local-postgres \
  --restart unless-stopped \
  -e POSTGRES_USER=aiqlick \
  -e POSTGRES_PASSWORD=aiqlick \
  -e POSTGRES_DB=aiqlick_db \
  -p 15432:5432 \
  pgvector/pgvector:pg16

# Redis
docker run -d \
  --name aiqlick-local-redis \
  --restart unless-stopped \
  -p 6379:6379 \
  redis:7

# MinIO (S3-compatible storage)
docker run -d \
  --name aiqlick-local-minio \
  --restart unless-stopped \
  -e MINIO_ROOT_USER=minioadmin \
  -e MINIO_ROOT_PASSWORD=minioadmin \
  -p 9000:9000 \
  -p 9001:9001 \
  minio/minio server /data --console-address ":9001"

Post-Setup: Enable pgvector

After starting PostgreSQL for the first time, connect and enable the vector extension:

docker exec -it aiqlick-local-postgres psql -U aiqlick -d aiqlick_db -c \
  "CREATE EXTENSION IF NOT EXISTS vector;"

This extension is required by the background tasks service for vector similarity search (RAG embeddings).

Startup Order

Services must be started in the correct order due to dependencies.

1. Infrastructure (Docker)

Ensure all three Docker containers are running:

docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

You should see aiqlick-local-postgres, aiqlick-local-redis, and aiqlick-local-minio in the output.

2. Backend (NestJS)

cd aiqlick-backend
npm install
npx prisma generate
npm run seed:essential
npm run start:dev

The backend starts on http://localhost:4001. The GraphQL playground is available at http://localhost:4001/graphql.

caution

Never run prisma migrate dev, prisma db push, or prisma migrate deploy locally. Schema changes are applied automatically during CI/CD deployment. Locally, only run npx prisma generate to regenerate the Prisma client after schema changes.

For a fresh local database, prisma db push --accept-data-loss may be needed as a one-time setup step.

3. Background Tasks (FastAPI)

cd background-tasks
pip install -r requirements.txt
export DATABASE_URL="postgresql://aiqlick:aiqlick@localhost:15432/aiqlick_db"
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

The background tasks service starts on http://localhost:8000. API documentation is at http://localhost:8000/docs.

4. Frontend (Next.js)

cd aiqlick-frontend
npm install
npm run dev

The frontend starts on http://localhost:4000 using Turbopack for fast development builds.

Environment Configuration

Each project has an example environment file that must be copied and configured.

Backend

Copy aiqlick-backend/.env.example to aiqlick-backend/.env and set:

Variable	Local Value	Description
DATABASE_URL	postgresql://aiqlick:aiqlick@localhost:15432/aiqlick_db	Local PostgreSQL
JWT_SECRET	Any random string	Token signing key
REDIS_HOST	localhost	Local Redis
REDIS_PORT	6379	Local Redis port
S3_ENDPOINT	http://localhost:9000	Local MinIO
S3_ACCESS_KEY	minioadmin	MinIO credentials
S3_SECRET_KEY	minioadmin	MinIO credentials
S3_BUCKET	aiqlick-uploads	Bucket name (create in MinIO console)
STRIPE_SECRET_KEY	Stripe test key	Payment processing

Frontend

Create aiqlick-frontend/.env.local with:

Variable	Local Value	Description
NEXT_PUBLIC_API_URL	http://localhost:4001	Backend API (also AI gateway HTTP + voice WS path)
NEXT_PUBLIC_GRAPHQL_WS_URL	ws://localhost:4001/graphql	Backend subscriptions (also subscribeAi for AI streaming)
NEXT_PUBLIC_APP_URL	http://localhost:4000	Frontend URL

Background-tasks runs on http://localhost:8000 for direct curl/dev tools, but the frontend never points at it directly — every AI call routes through the NestJS AI gateway on the backend. Set AI_BACKEND_GRAPHQL_URL=http://localhost:8000/graphql and AI_BACKEND_GRAPHQL_WS_URL=ws://localhost:8000/graphql in the backend .env so the gateway knows where its upstream lives.

Background Tasks

Copy background-tasks/.env.example to background-tasks/.env and set:

Variable	Local Value	Description
DATABASE_URL	postgresql://aiqlick:aiqlick@localhost:15432/aiqlick_db	Same database as backend

info

The backend and background tasks share the same PostgreSQL database. Schema is managed by Prisma in the backend project. Background tasks access the database using raw AsyncPG queries.

Common Development Tasks

Running Tests

# Backend unit tests
cd aiqlick-backend && npm run test:safe

# Backend single test file
cd aiqlick-backend && npm test -- path/to/file.spec.ts

# Background tasks unit tests
cd background-tasks && pytest -m unit

# Background tasks single test
cd background-tasks && pytest tests/unit/path/test_file.py::TestClass::test_name -v

Linting and Formatting

# Backend
cd aiqlick-backend && npm run lint && npm run format

# Background tasks
cd background-tasks && black app tests && isort app tests && flake8 app tests

# Frontend
cd aiqlick-frontend && npm run lint

Regenerating GraphQL Schema

After modifying resolvers in the backend:

cd aiqlick-backend && npm run schema:generate

This regenerates schema.gql from the resolver decorators.

Troubleshooting

PostgreSQL Connection Refused

Verify the container is running and the port mapping is correct:

docker logs aiqlick-local-postgres
docker port aiqlick-local-postgres

The local PostgreSQL runs on port 15432 (not the default 5432) to avoid conflicts with any system PostgreSQL installation.

Prisma Client Out of Date

If you see Prisma-related errors after pulling new schema changes:

cd aiqlick-backend && npx prisma generate

MinIO Bucket Not Found

Create the required bucket through the MinIO console at http://localhost:9001 or via the CLI:

docker exec aiqlick-local-minio mc mb /data/aiqlick-uploads

Frontend tsc --noEmit fails on .next/types/validator.ts

Symptom: running npx tsc --noEmit (or pre-commit) in aiqlick-frontend fails with TS2307: Cannot find module '../../../app/<some>/page.js' errors that all originate in .next/dev/types/validator.ts or .next/types/validator.ts. The page files referenced don't exist on disk.

Cause: Next regenerates .next/types/validator.ts on every next dev / next build from the current set of app/**/page.tsx files. When a route page is deleted but the validator artifact isn't regenerated, the validator's import of the now-missing page.js becomes the only stale TS reference in the project — and tsconfig.json includes .next/types/**/*.ts so tsc sees it.

Fix: clear the stale validator and let it regenerate.

rm -rf .next/types .next/dev/types
# either re-run `next dev` (it regenerates immediately) or `next build`

The .next/ folder is gitignored so this is purely a local-workflow issue — CI runs a fresh build and never sees stale validators. Don't try to "fix" the tsconfig include: the validator catches real route export type errors, that's why it's wired in.