# Demo Accounts

This document serves as the single source of truth for demo accounts in the GridPilot application.

## Overview

Demo accounts are predefined user accounts created during application bootstrap for testing and development purposes. They use a fixed password and are automatically seeded into the system.

## Available Demo Accounts

All demo accounts use the same fixed password: **`Demo1234!`**

| Email | Role | Display Name | Notes |
|-------|------|--------------|-------|
| `demo.driver@example.com` | user | John Driver | Standard user account with primary driver ID |
| `demo.sponsor@example.com` | user | Jane Sponsor | Standard user account |
| `demo.owner@example.com` | owner | Alice Owner | League owner account with admin privileges |
| `demo.steward@example.com` | user | Bob Steward | User account with admin privileges |
| `demo.admin@example.com` | admin | Charlie Admin | Administrator account |
| `demo.systemowner@example.com` | admin | Diana SystemOwner | Administrator account |
| `demo.superadmin@example.com` | admin | Edward SuperAdmin | Administrator account |

## How Demo Users Are Created

Demo users are created automatically during application startup through the bootstrap process:

1. **Bootstrap Module**: The `BootstrapModule` runs on API startup
2. **SeedDemoUsers**: This class creates/updates demo users with fixed specifications
3. **Idempotent**: If demo users already exist, they are only updated if force reseed is enabled
4. **Environment-aware**: Demo users are only created in development and test environments (never in production)

### Creation Process

- Users are created with deterministic IDs based on their email addresses
- Passwords are hashed using the password hashing service
- Admin users also get corresponding `AdminUser` entities with appropriate roles
- Users needing primary driver IDs get them generated based on their email

## Environment Variables

### `GRIDPILOT_API_BOOTSTRAP`
- **Purpose**: Controls whether bootstrap seeding runs on startup
- **Default**: `true` (enabled by default)
- **Values**: 
  - `true`, `1`, or any truthy value = enabled
  - `false`, `0` = disabled
- **Usage**: Set to `false` to skip all seeding (including demo users)

### `GRIDPILOT_API_FORCE_RESEED`
- **Purpose**: Forces reseeding of demo users even if they already exist
- **Default**: `false` (disabled)
- **Values**:
  - `true`, `1`, or any truthy value = enabled
  - `false`, `0` or unset = disabled
- **Usage**: Set to `true` to update existing demo users with new data

### `GRIDPILOT_API_PERSISTENCE`
- **Purpose**: Controls database persistence type
- **Values**: `postgres` or `inmemory`
- **Impact**: Demo users work with both persistence types

### `NODE_ENV`
- **Purpose**: Environment mode
- **Impact**: Demo users are only seeded in `development` and `test` environments, never in `production`

## How to Use Demo Accounts

### Login
Use the standard login API endpoint with any demo email and the password `Demo1234!`:

```bash
# Example login request
POST /api/auth/login
{
  "email": "demo.driver@example.com",
  "password": "Demo1234!"
}
```

### Access Demo Accounts
1. Start the application in development or test mode
2. Bootstrap will automatically create/update demo users
3. Use any demo email and password `Demo1234!` to log in
4. Different accounts have different roles and permissions for testing

## Forcing Reseed of Demo Users

To force reseeding of demo users (updates existing users):

### Option 1: Environment Variable
```bash
GRIDPILOT_API_FORCE_RESEED=true npm run dev
```

### Option 2: Docker Compose
Add to your `.env` file or docker-compose override:
```yaml
environment:
  - GRIDPILOT_API_FORCE_RESEED=true
```

### Option 3: Test Environment
Demo users are automatically reseeded in test environments when needed.

## Demo User Specifications

Each demo user is defined with these properties:
- **email**: Fixed email address
- **password**: Always `Demo1234!`
- **needsAdminUser**: Whether to create an AdminUser entity
- **needsPrimaryDriverId**: Whether to generate a primary driver ID
- **roles**: Array of roles for admin users
- **displayName**: Human-readable name

## Security Considerations

- Demo accounts should only be used in development and testing
- Never enable demo accounts in production
- The fixed password is acceptable for demo purposes but should never be used for real accounts
- Demo users have predictable emails, making them unsuitable for security testing

## Troubleshooting

### Demo Users Not Created
1. Check `NODE_ENV` is not `production`
2. Verify `GRIDPILOT_API_BOOTSTRAP` is not set to `false`
3. Check logs for bootstrap errors
4. Ensure database connection is working (for postgres persistence)

### Demo Users Not Updating
1. Set `GRIDPILOT_API_FORCE_RESEED=true` to force updates
2. Check that bootstrap is running on startup
3. Verify the SeedDemoUsers class is being called

### Want to Skip Demo Users
Set `GRIDPILOT_API_BOOTSTRAP=false` to skip all seeding, or modify the bootstrap logic to exclude demo user seeding specifically.