Friendolls Server

Backend API for the Friendolls application built with NestJS, Keycloak authentication, and Prisma ORM.

Tech Stack

• Framework: NestJS - Progressive Node.js framework
• Authentication: Keycloak - OpenID Connect (OIDC) / OAuth 2.0
• Database ORM: Prisma - Next-generation TypeScript ORM
• Database: PostgreSQL
• Language: TypeScript
• Package Manager: pnpm

Features

• ✅ Keycloak OIDC authentication with JWT tokens
• ✅ User management synchronized from Keycloak
• ✅ PostgreSQL database with Prisma ORM
• ✅ Swagger API documentation
• ✅ Role-based access control
• ✅ Global exception handling
• ✅ Environment-based configuration
• ✅ Comprehensive logging

Prerequisites

• Node.js 18+
• pnpm
• PostgreSQL 14+ (or Docker)
• Keycloak instance (for authentication)

Getting Started

1. Install Dependencies

pnpm install

2. Set Up Environment Variables

Create a .env file in the root directory:

# Server Configuration
PORT=3000
NODE_ENV=development

# Database
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/friendolls_dev?schema=public"

# Keycloak OIDC Configuration
JWKS_URI=https://your-keycloak-instance.com/realms/your-realm/protocol/openid-connect/certs
JWT_ISSUER=https://your-keycloak-instance.com/realms/your-realm
JWT_AUDIENCE=your-client-id

3. Set Up PostgreSQL Database

Option A: Using Docker (Recommended for development)

docker run --name friendolls-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=friendolls_dev \
  -p 5432:5432 \
  -d postgres:16-alpine

Option B: Use existing PostgreSQL installation

createdb friendolls_dev

See docs/PRISMA_SETUP.md for detailed database setup instructions.

4. Generate Prisma Client and Run Migrations

# Generate Prisma Client (creates TypeScript types)
pnpm prisma:generate

# Run migrations to create database schema
pnpm prisma:migrate

# If migration already exists, it will say "Already in sync"

Important: Always run pnpm prisma:generate after pulling new code or changing the Prisma schema.

5. Start the Development Server

pnpm start:dev

The server will be running at http://localhost:3000.

Available Scripts

Development

• pnpm start:dev - Start development server with hot reload
• pnpm start:debug - Start development server with debugging

Production

• pnpm build - Build the application
• pnpm start:prod - Start production server

Database (Prisma)

• pnpm prisma:generate - Generate Prisma Client
• pnpm prisma:migrate - Create and apply database migration
• pnpm prisma:migrate:deploy - Apply migrations in production
• pnpm prisma:studio - Open Prisma Studio (visual database browser)
• pnpm db:push - Push schema changes (dev only)
• pnpm db:reset - Reset database and reapply migrations

Code Quality

• pnpm lint - Lint the code
• pnpm format - Format code with Prettier

Testing

• pnpm test - Run unit tests
• pnpm test:watch - Run tests in watch mode
• pnpm test:cov - Run tests with coverage
• pnpm test:e2e - Run end-to-end tests

API Documentation

Once the server is running, access the Swagger API documentation at:

http://localhost:3000/api

Project Structure

friendolls-server/
├── prisma/                  # Prisma configuration
│   ├── migrations/         # Database migrations
│   └── schema.prisma       # Database schema
├── src/
│   ├── auth/               # Authentication module (Keycloak OIDC)
│   ├── common/             # Shared utilities and decorators
│   ├── config/             # Configuration
│   ├── database/           # Database module (Prisma)
│   │   ├── prisma.service.ts
│   │   └── database.module.ts
│   ├── users/              # Users module
│   │   ├── dto/           # Data Transfer Objects
│   │   ├── users.controller.ts
│   │   ├── users.service.ts
│   │   └── users.entity.ts
│   ├── app.module.ts       # Root application module
│   └── main.ts            # Application entry point
├── test/                   # E2E tests
├── .env                    # Environment variables (gitignored)
├── package.json
└── tsconfig.json

Database Schema

The application uses Prisma with PostgreSQL. The main entity is:

User Model

• Synchronized from Keycloak OIDC
• Stores user profile information
• Tracks login history
• Manages user roles

Authentication Flow

1. User authenticates via Keycloak
2. Keycloak issues JWT token
3. Client sends JWT in Authorization: Bearer <token> header
4. Server validates JWT against Keycloak's JWKS
5. User is automatically created/synced from token on first login
6. Subsequent requests update user's last login time

Development Workflow

1. Make schema changes in prisma/schema.prisma
2. Create migration: pnpm prisma:migrate
3. Implement business logic in services
4. Create/update DTOs for request validation
5. Update controllers for API endpoints
6. Test your changes
7. Lint and format: pnpm lint && pnpm format
8. Commit your changes

Environment Variables

Variable	Description	Required	Example
PORT	Server port	No (default: 3000)	3000
NODE_ENV	Environment	No	development, production
DATABASE_URL	PostgreSQL connection string	Yes	postgresql://user:pass@host:5432/db
JWKS_URI	Keycloak JWKS endpoint	Yes	https://keycloak.com/realms/myrealm/protocol/openid-connect/certs
JWT_ISSUER	JWT issuer (Keycloak realm)	Yes	https://keycloak.com/realms/myrealm
JWT_AUDIENCE	JWT audience (client ID)	Yes	my-client-id

Production Deployment

1. Set environment variables (especially DATABASE_URL)
2. Install dependencies: pnpm install --prod
3. Generate Prisma Client: pnpm prisma:generate
4. Run migrations: pnpm prisma:migrate:deploy
5. Build application: pnpm build
6. Start server: pnpm start:prod