# Database Setup Guide

## Database Location

**Primary Database**: `apps/admin/data/fitai.db`

This is the single source of truth for all application data. All API routes, migration scripts, and database operations use this file.

## Database Path Configuration

### Database Package (`@fitai/database`)

The database package supports configurable paths via environment variables:

```typescript
// Default behavior:
// - Development: ../../apps/admin/data/fitai.db
// - Production: ./data/fitai.db
// - Custom: Set DATABASE_URL environment variable
```

**Environment Variable**:
```bash
# Optional: Override default database path
DATABASE_URL=/path/to/your/fitai.db
```

### Admin App

The admin app uses the following database path configuration:

```typescript
// Default: ./data/fitai.db (relative to apps/admin/)
filename: './data/fitai.db'
```

All API routes and scripts use this consistent path.

## Migration Scripts

All migration scripts are located in `apps/admin/scripts/` and use the correct database path:

- `seed-superadmin.js` - Creates super admin user
- `migrate-roles.js` - Adds role column to users table
- `migrate-fitness-profile.js` - Adds allergies and injuries columns
- `migrate-last-visit.js` - Adds lastVisit column to clients table

**Running Migrations**:
```bash
cd apps/admin
node scripts/migrate-fitness-profile.js
node scripts/migrate-roles.js
node scripts/migrate-last-visit.js
```

## Drizzle ORM

Drizzle Kit is configured to use the admin database:

```typescript
// packages/database/drizzle.config.ts
dbCredentials: {
  url: "../../apps/admin/data/fitai.db"
}
```

**Drizzle Commands**:
```bash
cd packages/database

# Push schema changes to database
npm run db:push

# Open Drizzle Studio (database GUI)
npm run db:studio
```

## Backup and Restore

### Creating a Backup

```bash
# From project root
cp apps/admin/data/fitai.db backups/fitai-$(date +%Y%m%d-%H%M%S).db
```

### Restoring from Backup

```bash
# From project root
cp backups/fitai-YYYYMMDD-HHMMSS.db apps/admin/data/fitai.db
```

## Database Schema

The database uses SQLite with the following main tables:

- `users` - User accounts (admin, trainer, client)
- `clients` - Client profiles linked to users
- `fitness_profiles` - Fitness goals, preferences, and health info
- `payments` - Payment records
- `attendance` - Check-in/check-out records
- `notifications` - User notifications
- `recommendations` - AI-generated fitness recommendations

## Troubleshooting

### Database Not Found Error

If you see "database not found" errors:

1. Ensure you're running commands from the correct directory
2. Check that `apps/admin/data/fitai.db` exists
3. Verify file permissions (should be readable/writable)

### Multiple Database Files

**There should only be ONE database file**: `apps/admin/data/fitai.db`

If you find other `fitai.db` files:
- `data/fitai.db` (root level) - Old duplicate, should not exist
- `packages/database/fitai.db` - Old duplicate, should not exist

These were consolidated on 2025-11-26. Backups are in `backups/database-consolidation-2025-11-26/`.

### Migration Script Errors

If migration scripts fail:

1. Check that you're in the `apps/admin` directory
2. Verify the database file exists and is writable
3. Check the script output for specific error messages
4. Ensure no other process has the database locked

## Development Workflow

### Starting Fresh

```bash
# Remove existing database
rm apps/admin/data/fitai.db

# Run migrations to create tables
cd packages/database
npm run db:push

# Seed super admin user
cd ../../apps/admin
node scripts/seed-superadmin.js
```

### Viewing Database Contents

**Option 1: Drizzle Studio (Recommended)**
```bash
cd packages/database
npm run db:studio
# Opens at http://localhost:4983
```

**Option 2: SQLite CLI**
```bash
cd apps/admin/data
sqlite3 fitai.db
# Then run SQL queries
SELECT * FROM users;
.exit
```

**Option 3: VS Code Extension**
Install "SQLite Viewer" extension and open `apps/admin/data/fitai.db`

## Production Deployment

### Environment Variables

Set the following in production:

```bash
# Optional: Custom database path
DATABASE_URL=/var/data/fitai.db

# Set production mode
NODE_ENV=production
```

### Database Location in Production

Ensure the database directory exists and has proper permissions:

```bash
mkdir -p /path/to/data
chmod 755 /path/to/data
```

### Backup Strategy

Implement automated backups in production:

```bash
# Daily backup cron job
0 2 * * * cp /var/data/fitai.db /var/backups/fitai-$(date +\%Y\%m\%d).db
```

## Security Considerations

1. **Never commit the database file to git** - It's in `.gitignore`
2. **Protect database file permissions** - Only application should have access
3. **Regular backups** - Implement automated backup strategy
4. **Encryption at rest** - Consider encrypting the database file in production
5. **Access control** - Ensure only authorized users can access the database

## Related Documentation

- [Clerk Webhook Setup](./CLERK_WEBHOOK_SETUP.md) - User synchronization
- [Testing Fitness Profile](./TESTING_FITNESS_PROFILE.md) - Feature testing
- [Webhook Database Fix](./WEBHOOK_DATABASE_FIX.md) - Webhook implementation details