FaceLocker Backend

A NestJS-based backend API for the FaceLocker system - a secure locker management platform with authentication, media handling, QR token generation, and session management.

Project Overview

FaceLocker is a comprehensive backend system that manages:

• User Management - User profiles and authentication
• Authentication - JWT-based auth, Keycloak integration, Apple OAuth
• Locker Management - Create, manage, and track lockers
• QR Tokens - Generate and validate QR codes for locker access
• Media Handling - Upload and manage media files with S3 integration
• Sessions - Track user sessions and access history
• Role-Based Access Control - Fine-grained permission management

Tech Stack

• Framework: NestJS 11
• Language: TypeScript
• Database: PostgreSQL with TypeORM
• Authentication: Keycloak + JWT
• API Documentation: Swagger/OpenAPI
• File Storage: AWS S3
• Pattern: CQRS (Command Query Responsibility Segregation)
• Containerization: Docker & Docker Compose

Project Structure

backend/
├── src/
│   ├── modules/          # Core feature modules
│   │   ├── auth/        # Authentication & authorization
│   │   ├── keycloak/    # Keycloak integration
│   │   ├── user/        # User management
│   │   ├── lockers/     # Locker CRUD operations
│   │   ├── sessions/    # Session tracking
│   │   ├── media/       # Media file handling
│   │   ├── qr-tokens/   # QR code generation
│   │   └── s3/          # AWS S3 adapter
│   ├── shared/          # Shared utilities & configurations
│   ├── decorator/       # Custom decorators
│   ├── filter/          # Exception filters
│   ├── guards/          # Route guards & role checks
│   └── main.ts          # Application entry point
└── dist/                # Compiled output

Quick Start

Prerequisites

• Node.js 18+
• Docker & Docker Compose
• PostgreSQL (optional, if not using Docker)

Installation

1. Clone & Install Dependencies

   cd backend
   npm install

2. Environment Configuration

   # Copy and configure .env file
   cp .env.example .env

3. Database Setup

   npm run migration-run
   npm run migration-seed

Running the Application

Development Mode (with hot reload)

npm run start:dev

Production Mode

npm run build
npm run start:prod

Debug Mode

npm run start:debug

Docker Deployment

Run the entire stack with Docker Compose:

docker-compose up -d

This starts:

• FaceLocker Backend (NestJS)
• PostgreSQL Database
• Keycloak Authentication Server

Common Commands

Command	Purpose
npm run build	Build for production
npm run lint	Run ESLint with auto-fix
npm run test	Run unit tests
npm run test:cov	Generate test coverage
npm run test:e2e	Run end-to-end tests
npm run migration-generate	Auto-generate migrations
npm run migration-run	Execute pending migrations
npm run schema-drop	Drop database schema (⚠️ destructive)

API Documentation

Once the server is running, visit:

http://localhost:3000/api/docs

The Swagger UI provides interactive API documentation with request/response examples.

Authentication

The system uses JWT tokens from Keycloak:

1. User authenticates via Keycloak
2. Receives JWT token
3. Includes token in Authorization: Bearer <token> header
4. Backend verifies token and enforces role-based access

Supported OAuth providers:

• Keycloak (primary)
• Apple OAuth

Database Migrations

• Migrations are version-controlled in src/shared/infra/typeorm/migrations/
• Auto-generate migrations after schema changes:

  npm run migration-generate -- -n MigrationName

Contributing

1. Follow TypeScript strict mode
2. Maintain CQRS pattern in modules
3. Add unit tests for features
4. Run linter before committing:

   npm run format && npm run lint

License

UNLICENSED (Private Project)

Support

For issues, refer to:

• NestJS Documentation
• TypeORM Documentation
• Keycloak Documentation