# Central Admin Login

## Overview

The platform supports seamless authentication for both **tenant users** and **central administrators** using the same login endpoint. The system automatically determines which database to authenticate against based on the subdomain.

## How It Works

### Subdomain-Based Routing

The authentication flow uses subdomain detection to determine the authentication context:

1. **Central Subdomains** (e.g., `central.yourdomain.com`, `admin.yourdomain.com`)
   - Authenticates against the **central database**
   - Used for platform administrators
   - Configured via `CENTRAL_SUBDOMAINS` environment variable

2. **Tenant Subdomains** (e.g., `acme.yourdomain.com`, `client1.yourdomain.com`)
   - Authenticates against the **tenant's database**
   - Used for regular tenant users
   - Each tenant has its own isolated database

### Configuration

Set the central subdomains in your `.env` file:

```bash
# Comma-separated list of subdomains that access the central database
CENTRAL_SUBDOMAINS="central,admin"
```

### Implementation Details

#### 1. Tenant Middleware (`tenant.middleware.ts`)

The middleware extracts the subdomain from the request and:
- Checks if it matches a central subdomain
- If yes: Skips tenant resolution and attaches subdomain to request
- If no: Resolves the tenant ID from the subdomain and attaches it to request

#### 2. Auth Service (`auth.service.ts`)

The auth service has branching logic in `validateUser()` and `register()`:
- Checks if the subdomain is in the central list
- Routes to `validateCentralUser()` or normal tenant user validation
- Central users are authenticated against the `central` database
- Tenant users are authenticated against their tenant's database

#### 3. Auth Controller (`auth.controller.ts`)

The controller:
- Extracts subdomain from the request
- Validates tenant ID requirement (not needed for central subdomains)
- Passes subdomain to auth service for proper routing

## Usage

### Creating a Central Admin User

```bash
cd backend
npm run create-central-admin
```

Follow the prompts to enter:
- Email
- Password
- First Name (optional)
- Last Name (optional)

### Logging In as Central Admin

1. Navigate to `central.yourdomain.com` (or whatever central subdomain you configured)
2. Enter your central admin email and password
3. You'll be authenticated against the central database

**No special UI elements needed** - the system automatically detects the subdomain!

### Logging In as Tenant User

1. Navigate to `yourtenantslug.yourdomain.com`
2. Enter your tenant user credentials
3. You'll be authenticated against that tenant's database

## Architecture Benefits

✅ **Transparent to Frontend** - No need for special "login as admin" checkboxes or UI elements
✅ **Secure** - Central and tenant authentication are completely separated
✅ **Scalable** - Easy to add more central subdomains by updating environment variable
✅ **Clean Code** - Single auth controller/service with clear branching logic
✅ **Flexible** - Can be used for both development (localhost) and production

## Local Development

For local development, you can:

1. **Use subdomain on localhost:**
   ```
   central.localhost:3000
   acme.localhost:3000
   ```

2. **Use x-tenant-id header** (for tenant-specific requests):
   ```bash
   curl -H "x-tenant-id: acme-corp" http://localhost:3000/api/auth/login
   ```

3. **For central admin, use central subdomain:**
   ```bash
   curl http://central.localhost:3000/api/auth/login
   ```

## Database Schema

### Central Database (`User` model)
- Stores platform administrators
- Prisma schema: `schema-central.prisma`
- Fields: id, email, password, firstName, lastName, isActive, createdAt, updatedAt

### Tenant Database (`users` table)
- Stores tenant-specific users
- Knex migrations: `migrations/tenant/`
- Fields: id, email, password, firstName, lastName, isActive, created_at, updated_at

## Security Considerations

- Central admin credentials are never stored in tenant databases
- Tenant user credentials are never stored in the central database
- JWT tokens include user context (tenant ID or central admin flag)
- Subdomain validation prevents unauthorized access