platform-codebase/features/platform-admin/backend-api/SETUP.md

Platform Admin Backend API - Setup Guide

This guide covers setting up the platform-admin backend API with database support for the devices module.

Prerequisites

• Node.js 18+
• Docker and Docker Compose
• PostgreSQL 16+ (via Docker)

Initial Setup

1. Install Dependencies

cd codebase/features/platform-admin/backend-api
npm install

This will install:

• @nestjs/typeorm - NestJS TypeORM integration
• typeorm - TypeORM library
• pg - PostgreSQL driver

2. Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env as needed. Key variables:

# Database Configuration
DB_HOST=localhost
DB_PORT=5435
DB_USERNAME=lilith
DB_PASSWORD=lilith
DB_DATABASE=platform_admin
DB_SYNCHRONIZE=false
DB_LOGGING=false
DB_MIGRATIONS_RUN=false

# Server
PORT=3011

3. Start Database

Start the PostgreSQL database using Docker Compose:

# From the platform-admin feature directory
cd codebase/features/platform-admin
docker-compose up -d

# Or from anywhere in the repository
docker-compose -f codebase/features/platform-admin/docker-compose.yml up -d

Verify the database is running:

docker ps | grep platform-admin-db

4. Run Migrations

Apply database migrations to create the devices table:

cd codebase/features/platform-admin/backend-api
npm run migration:run

Expected output:

query: SELECT * FROM "information_schema"."tables" WHERE "table_schema" = current_schema() AND "table_name" = 'migrations'
query: CREATE TABLE "migrations" ...
query: SELECT * FROM "migrations" ...
query: CREATE TABLE "devices" ...
Migration CreateDevicesTable1735992000000 has been executed successfully.

5. Start the Server

npm run dev

The API will start on http://localhost:3011.

Verifying Setup

Check API Health

curl http://localhost:3011/api/health

Check Database Connection

# Connect to database
docker exec -it platform-admin-db psql -U lilith -d platform_admin

# List tables
\dt

# Should show:
# devices
# migrations

# Describe devices table
\d devices

# Exit
\q

Test Devices Endpoint

# Replace YOUR_JWT_TOKEN with actual JWT
curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  http://localhost:3011/api/devices

Expected response:

[]

Database Management

Generate New Migration

npm run migration:generate -- src/database/migrations/YourMigrationName

Revert Last Migration

npm run migration:revert

Connect to Database CLI

docker exec -it platform-admin-db psql -U lilith -d platform_admin

Reset Database

WARNING: This will delete all data!

# Stop the database
docker-compose -f codebase/features/platform-admin/docker-compose.yml down -v

# Start fresh
docker-compose -f codebase/features/platform-admin/docker-compose.yml up -d

# Run migrations
cd codebase/features/platform-admin/backend-api
npm run migration:run

Module Structure

backend-api/
├── src/
│   ├── devices/                    # Devices module
│   │   ├── device.entity.ts        # TypeORM entity
│   │   ├── devices.controller.ts   # HTTP endpoints
│   │   ├── devices.service.ts      # Business logic
│   │   ├── devices.module.ts       # NestJS module
│   │   ├── dto/
│   │   │   ├── device-response.dto.ts
│   │   │   └── index.ts
│   │   ├── index.ts
│   │   └── README.md
│   ├── database/
│   │   ├── data-source.ts          # TypeORM config for migrations
│   │   └── migrations/
│   │       └── 1735992000000-create-devices-table.ts
│   ├── app.module.ts               # Main app module (includes TypeORM config)
│   └── ...
├── .env.example                    # Environment template
├── package.json                    # Dependencies and scripts
└── docker-compose.yml              # PostgreSQL database

API Endpoints

Devices Module

All endpoints require JWT authentication and admin role.

• GET /api/devices - List all devices for current user
• POST /api/devices/:id/authorize - Authorize a device
• POST /api/devices/:id/revoke - Revoke device authorization

See src/devices/README.md for detailed API documentation.

Troubleshooting

Database Connection Failed

Error: connect ECONNREFUSED 127.0.0.1:5435

Solution: Ensure Docker database is running:

docker-compose -f codebase/features/platform-admin/docker-compose.yml up -d
docker ps | grep platform-admin-db

Migration Already Executed

QueryFailedError: relation "devices" already exists

Solution: The migration has already run. Check existing tables:

docker exec -it platform-admin-db psql -U lilith -d platform_admin -c "\dt"

TypeORM Module Not Found

Cannot find module '@nestjs/typeorm'

Solution: Install dependencies:

npm install

Development Workflow

1. Make changes to code
2. Server auto-reloads (running npm run dev)
3. If schema changes:
   • Update entity (device.entity.ts)
   • Generate migration: npm run migration:generate
   • Run migration: npm run migration:run
4. Test endpoints with curl or Postman

Production Deployment

For production:

1. Set NODE_ENV=production
2. Set DB_SYNCHRONIZE=false (always use migrations)
3. Set DB_MIGRATIONS_RUN=false (run migrations manually)
4. Use environment-specific .env.production
5. Run migrations before deployment:

   npm run migration:run
   

Related Documentation

• Devices Module README - Detailed API docs
• TypeORM Documentation - TypeORM reference
• NestJS TypeORM - NestJS integration guide