Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Codefied-CodePix/Karokar-backend/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through setting up a local KaroKar Backend instance from scratch. You will clone the repository, wire up a PostgreSQL database, run TypeORM migrations, and fire a real API request against the running server. The entire flow should take fewer than five minutes on a machine that already has Node.js and PostgreSQL installed.
Never ship the default JWT_SECRET to any shared or production environment. The value change-me-in-production in .env.example is a placeholder only. Generate a cryptographically random secret (e.g. openssl rand -hex 64) and store it in your secrets manager before deploying.

​
Prerequisites

  • Node.js ≥ 18 and npm ≥ 9
  • PostgreSQL ≥ 14 running locally (or a remote connection string)
  • Git
1

Clone the repository and install dependencies

Clone the repo and install all Node dependencies with a single command.
git clone https://github.com/Codefied-CodePix/Karokar-backend.git
cd Karokar-backend
npm install
npm install resolves both production dependencies (NestJS, TypeORM, Passport, etc.) and dev dependencies (TypeScript compiler, NestJS CLI schematics, type definitions).
2

Configure your environment

Copy the example environment file and update the values for your local setup.
cp .env.example .env
The .env.example ships with these defaults:
NODE_ENV=development
PORT=3000

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/karokar

JWT_SECRET=change-me-in-production
VariableDescription
NODE_ENVRuntime environment. Use development locally.
PORTHTTP port the server binds to. Defaults to 3000.
DATABASE_URLFull PostgreSQL connection string. Create the karokar database before running migrations.
JWT_SECRETSecret used to sign and verify JWT tokens. Must be changed in production.
Create the database if it does not exist yet:
CREATE DATABASE karokar;
The TypeORM connection is configured with synchronize: false, which means the schema is never auto-updated at startup. All schema changes are managed exclusively through migrations — see the next step.
3

Run database migrations

KaroKar uses TypeORM migrations (via src/database/data-source.ts) to manage the schema. Apply all pending migrations to your database:
npm run migration:run
Under the hood this runs:
typeorm-ts-node-commonjs -d src/database/data-source.ts migration:run
You should see each migration logged as it is applied. If you need to roll back the most recent migration:
npm run migration:revert
4

Start the development server

Launch the NestJS application in watch mode. The compiler will rebuild and reload on every file change.
npm run start:dev
Once bootstrapped, the server is available at the port defined in your .env (default 3000):
[Nest] LOG [NestApplication] Nest application successfully started
Application is running on: http://localhost:3000
A global ValidationPipe is applied at bootstrap with whitelist: true, forbidNonWhitelisted: true, and transform: true. This means any request body property that is not declared in the corresponding DTO is automatically stripped, and extra unknown properties cause a 400 Bad Request rather than being silently ignored. Always model your request bodies against the published DTOs.
5

Make your first API call

The POST /users endpoint creates a new user in the Identity domain and requires the employee.manage permission encoded in a valid JWT.Request:
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_jwt_token>" \
  -d '{
    "firstName": "Ayesha",
    "lastName": "Khan",
    "email": "ayesha.khan@example.com",
    "phone": "+923001234567"
  }'
FieldTypeDescription
firstNamestringUser’s given name
lastNamestringUser’s family name
emailstringUnique email address
phonestring (optional)Contact phone number
A successful response returns 201 Created with the newly created user resource. A missing or expired token returns 401 Unauthorized; insufficient permissions return 403 Forbidden.

​
Next Steps

  • Read the Architecture guide to understand bounded contexts, module structure, and the non-negotiable rules enforced across the codebase.
  • Review the Introduction for a full overview of participant types and the tech stack.

Build docs developers (and LLMs) love

Get started for freeTalk to us