the-biergarten-app/docs/database.md

# Database Schema

This document describes the database schema, stored procedures, and data access patterns for The Biergarten App.

## Overview

The Biergarten App uses **SQL Server 2022** with a **SQL-first approach**:
- All queries via stored procedures
- No ORM (no Entity Framework)
- Database-driven validation and integrity
- Version-controlled migrations using DbUp

See the [database-schema diagram](diagrams/pdf/database-schema.pdf) for visual representation.

## Schema Overview

The database is organized into several logical domains:

### User Management

Core user account and authentication tables.

#### UserAccount
Primary user profile table.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| UserAccountId | INT | PK, IDENTITY | Primary key |
| Username | NVARCHAR(30) | UNIQUE, NOT NULL | Unique username |
| Email | NVARCHAR(255) | UNIQUE, NOT NULL | Email address |
| FirstName | NVARCHAR(50) | NOT NULL | First name |
| LastName | NVARCHAR(50) | NOT NULL | Last name |
| Bio | NVARCHAR(500) | NULL | User bio |
| CreatedAt | DATETIME2 | NOT NULL | Account creation timestamp |
| UpdatedAt | DATETIME2 | NOT NULL | Last update timestamp |
| LastLoginAt | DATETIME2 | NULL | Last successful login |

**Indexes**:
- Unique index on `Username`
- Unique index on `Email`
- Index on `CreatedAt` for sorting

#### UserCredential
Authentication credentials with password hashes.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| UserCredentialId | INT | PK, IDENTITY | Primary key |
| UserAccountId | INT | FK → UserAccount | User reference |
| PasswordHash | VARBINARY(32) | NOT NULL | Argon2id hash (256-bit) |
| PasswordSalt | VARBINARY(16) | NOT NULL | Random salt (128-bit) |
| IsActive | BIT | NOT NULL | Active credential flag |
| CredentialRotatedAt | DATETIME2 | NULL | Last password change |
| CredentialExpiresAt | DATETIME2 | NULL | Password expiration |
| CredentialRevokedAt | DATETIME2 | NULL | Revocation timestamp |
| CreatedAt | DATETIME2 | NOT NULL | Creation timestamp |

**Notes**:
- Users can have multiple credentials (rotation support)
- Only one active credential per user
- Expired/revoked credentials retained for audit

**Password Hashing**:
- Algorithm: Argon2id
- Memory: 64MB
- Iterations: 4
- Parallelism: CPU core count
- Salt: Cryptographically random 128-bit
- Hash: 256-bit output

#### UserVerification
Email verification and account activation.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| UserVerificationId | INT | PK, IDENTITY | Primary key |
| UserAccountId | INT | FK → UserAccount | User reference |
| IsVerified | BIT | NOT NULL, DEFAULT 0 | Verification status |
| VerifiedAt | DATETIME2 | NULL | Verification timestamp |
| VerificationToken | NVARCHAR(255) | NULL | Email token |
| TokenExpiresAt | DATETIME2 | NULL | Token expiration |

#### UserAvatar
User profile pictures.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| UserAvatarId | INT | PK, IDENTITY | Primary key |
| UserAccountId | INT | FK → UserAccount | User reference |
| PhotoId | INT | FK → Photo | Image reference |
| IsActive | BIT | NOT NULL | Active avatar flag |
| CreatedAt | DATETIME2 | NOT NULL | Upload timestamp |

#### UserFollow
Social following relationships.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| UserFollowId | INT | PK, IDENTITY | Primary key |
| FollowerUserId | INT | FK → UserAccount | User who follows |
| FollowedUserId | INT | FK → UserAccount | User being followed |
| CreatedAt | DATETIME2 | NOT NULL | Follow timestamp |

**Constraints**:
- Unique constraint on (FollowerUserId, FollowedUserId)
- Check constraint: FollowerUserId ≠ FollowedUserId

### Location Data

Geographic reference data for breweries and users.

#### Country
ISO 3166-1 country codes.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| CountryId | INT | PK, IDENTITY | Primary key |
| CountryCode | CHAR(2) | UNIQUE, NOT NULL | ISO 3166-1 alpha-2 |
| CountryName | NVARCHAR(100) | NOT NULL | Country name |

#### StateProvince
States, provinces, and regions (ISO 3166-2).

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| StateProvinceId | INT | PK, IDENTITY | Primary key |
| CountryId | INT | FK → Country | Country reference |
| StateProvinceCode | NVARCHAR(10) | NOT NULL | ISO 3166-2 code |
| StateProvinceName | NVARCHAR(100) | NOT NULL | State/province name |

#### City
Cities and municipalities.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| CityId | INT | PK, IDENTITY | Primary key |
| StateProvinceId | INT | FK → StateProvince | State/province ref |
| CityName | NVARCHAR(100) | NOT NULL | City name |
| Latitude | DECIMAL(9,6) | NULL | Latitude coordinate |
| Longitude | DECIMAL(9,6) | NULL | Longitude coordinate |

### Content

Brewery and beer content tables.

#### BreweryPost
Brewery information posts.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| BreweryPostId | INT | PK, IDENTITY | Primary key |
| UserAccountId | INT | FK → UserAccount | Author |
| BreweryName | NVARCHAR(200) | NOT NULL | Brewery name |
| Description | NVARCHAR(MAX) | NULL | Description |
| CreatedAt | DATETIME2 | NOT NULL | Creation timestamp |
| UpdatedAt | DATETIME2 | NOT NULL | Last update |

#### BreweryPostLocation
Geospatial data for breweries.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| BreweryPostLocationId | INT | PK, IDENTITY | Primary key |
| BreweryPostId | INT | FK → BreweryPost | Brewery reference |
| CityId | INT | FK → City | City reference |
| Address | NVARCHAR(255) | NULL | Street address |
| Location | GEOGRAPHY | NULL | Spatial data |

**Spatial Index**: On `Location` column for geospatial queries.

#### BeerPost
Individual beer posts.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| BeerPostId | INT | PK, IDENTITY | Primary key |
| BreweryPostId | INT | FK → BreweryPost | Brewery ref |
| UserAccountId | INT | FK → UserAccount | Author |
| BeerName | NVARCHAR(200) | NOT NULL | Beer name |
| Description | NVARCHAR(MAX) | NULL | Description |
| ABV | DECIMAL(4,2) | NULL | Alcohol by volume |
| IBU | INT | NULL | International Bitterness Units |
| BeerStyleId | INT | FK → BeerStyle | Style category |
| CreatedAt | DATETIME2 | NOT NULL | Creation timestamp |

#### Photo
Image metadata.

| Column | Type | Constraints | Description |
|--------|------|-------------|-------------|
| PhotoId | INT | PK, IDENTITY | Primary key |
| Url | NVARCHAR(500) | NOT NULL | Image URL |
| CloudinaryPublicId | NVARCHAR(255) | NULL | Cloudinary ID |
| Width | INT | NULL | Image width |
| Height | INT | NULL | Image height |
| Format | NVARCHAR(10) | NULL | Image format |
| CreatedAt | DATETIME2 | NOT NULL | Upload timestamp |

## Stored Procedures

All data access is performed through stored procedures for:
- Performance optimization
- Centralized business logic
- Enhanced security
- Better query plan caching

### User Management Procedures

#### USP_RegisterUser
Creates a new user account with credentials.

**Parameters**:
- `@Username` - Unique username
- `@Email` - Email address
- `@FirstName` - First name
- `@LastName` - Last name
- `@PasswordHash` - Argon2id hash
- `@PasswordSalt` - Random salt

**Returns**: `UserAccountId` of created user

**Logic**:
1. Validates username and email uniqueness
2. Creates UserAccount record
3. Creates UserCredential record
4. Creates UserVerification record (unverified)
5. Returns user ID

#### USP_GetUserAccountByUsername
Retrieves user account and credential by username.

**Parameters**:
- `@Username` - Username to look up

**Returns**: User account details + active credential

#### USP_RotateUserCredential
Updates user password (credential rotation).

**Parameters**:
- `@UserAccountId` - User ID
- `@NewPasswordHash` - New password hash
- `@NewPasswordSalt` - New salt

**Logic**:
1. Deactivates current credential
2. Creates new active credential
3. Updates CredentialRotatedAt timestamp

### Location Procedures

#### USP_CreateCountry
Inserts a new country or retrieves existing.

#### USP_CreateStateProvince
Inserts a state/province or retrieves existing.

#### USP_CreateCity
Inserts a city or retrieves existing.

## Data Seeding

The `Database.Seed` project populates development/test databases with:

### Location Data
- 3 countries (US, Canada, Mexico)
- 50 US states + DC
- 13 Canadian provinces/territories
- 32 Mexican states
- Major cities for each region

### Test Users
- Admin account
- Sample user accounts with verified emails

### Sample Data (Future)
- Breweries
- Beer styles
- Sample posts

## Migrations

### DbUp Migration Strategy

**Migration Files**: `src/Core/Database/Database.Migrations/scripts/`

**Naming Convention**: `###-DescriptiveName.sql`
- `001-CreateUserTables.sql`
- `002-CreateLocationTables.sql`
- `003-CreateContentTables.sql`

**Execution**:
- Migrations run on container startup
- Tracked in `SchemaVersions` table
- Idempotent (safe to run multiple times)
- Sequential execution order

**Development Mode**:
Set `CLEAR_DATABASE=true` to drop and recreate (dev/test only).

### Adding New Migrations

1. Create new SQL file in `scripts/` folder
2. Use next sequential number
3. Write idempotent SQL
4. Test locally before committing
5. Rebuild migration container

**Example Migration**:
```sql
-- 004-AddUserBio.sql
IF NOT EXISTS (
    SELECT * FROM sys.columns
    WHERE object_id = OBJECT_ID('UserAccount')
    AND name = 'Bio'
)
BEGIN
    ALTER TABLE UserAccount
    ADD Bio NVARCHAR(500) NULL;
END
GO
```

## Query Performance

### Indexes

Strategic indexes for common queries:
- Username lookup (unique index)
- Email lookup (unique index)
- User followers (composite index)
- Brewery location (spatial index)
- Created date sorting

###Execution Plans

Stored procedures allow SQL Server to:
- Cache execution plans
- Optimize query performance
- Reduce compilation overhead
- Enable query hints when needed

## Backup & Recovery

### Development
No backup strategy (fresh database from migrations).

### Production (Future)
- Automated daily backups
- Point-in-time recovery
- Geo-redundant storage
- Backup retention policy

## Monitoring

### Queries to Monitor
- User login frequency
- Slow-running procedures
- Lock contention
- Index fragmentation

### Tools
- SQL Server Management Studio (SSMS)
- JetBrains Rider