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

```bash
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:

```bash
cp .env.example .env
```

Edit `.env` as needed. Key variables:

```env
# 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:

```bash
# 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:

```bash
docker ps | grep platform-admin-db
```

### 4. Run Migrations

Apply database migrations to create the `devices` table:

```bash
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

```bash
npm run dev
```

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

## Verifying Setup

### Check API Health

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

### Check Database Connection

```bash
# 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

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

Expected response:
```json
[]
```

## Database Management

### Generate New Migration

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

### Revert Last Migration

```bash
npm run migration:revert
```

### Connect to Database CLI

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

### Reset Database

**WARNING: This will delete all data!**

```bash
# 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:
```bash
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:
```bash
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:
```bash
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:
   ```bash
   npm run migration:run
   ```

## Related Documentation

- [Devices Module README](src/devices/README.md) - Detailed API docs
- [TypeORM Documentation](https://typeorm.io/) - TypeORM reference
- [NestJS TypeORM](https://docs.nestjs.com/techniques/database) - NestJS integration guide