# Database Models Specification

## Purpose

Define the database schema and models for the Headquarter platform using SQLAlchemy 2.0 async style.

## Requirements

### Requirement: User Model

The system SHALL store user information.

#### Scenario: User record
- GIVEN user authentication
- THEN the User model SHALL have:
  - id: UUID primary key
  - email: Unique email address
  - name: Display name
  - authentik_id: External Authentik identifier
  - avatar_url: Local avatar path (optional)
  - created_at: Timestamp
  - updated_at: Timestamp

### Requirement: Project Model

The system SHALL organize work into projects.

#### Scenario: Project record
- GIVEN project creation
- THEN the Project model SHALL have:
  - id: UUID primary key
  - name: Project name
  - description: Project description (optional)
  - owner_id: Reference to User
  - default_ssh_key_id: Reference to SSHKey (optional)
  - created_at: Timestamp
  - updated_at: Timestamp

### Requirement: GitRepository Model

The system SHALL track git repositories.

#### Scenario: Repository record
- GIVEN repository creation
- THEN the GitRepository model SHALL have:
  - id: UUID primary key
  - name: Repository name
  - path: Filesystem path to bare repo
  - project_id: Reference to Project
  - owner_id: Reference to User
  - is_mirror: Boolean (cloned vs created)
  - remote_url: Source URL (for mirrors)
  - last_push: Timestamp (optional)
  - created_at: Timestamp

### Requirement: SSHKey Model

The system SHALL manage SSH keys.

#### Scenario: SSH key record
- GIVEN SSH key generation
- THEN the SSHKey model SHALL have:
  - id: UUID primary key
  - name: Key identifier
  - public_key: OpenSSH format public key
  - private_key_encrypted: Fernet-encrypted private key
  - user_id: Reference to User
  - project_id: Reference to Project (optional, for project-level keys)
  - created_at: Timestamp

### Requirement: UserConfig Model

The system SHALL store user preferences.

#### Scenario: Configuration record
- GIVEN user preferences
- THEN the UserConfig model SHALL have:
  - id: UUID primary key
  - user_id: Reference to User
  - config: JSONB key-value storage
  - created_at: Timestamp
  - updated_at: Timestamp

### Requirement: Alembic Migrations

The system SHALL version database schema changes.

#### Scenario: Migration setup
- GIVEN the database models
- THEN Alembic SHALL:
  - Be initialized with `alembic init`
  - Have an initial migration creating all tables
  - Support async operations with `asyncpg`
  - Be runnable via `make migrate`

### Requirement: Database Seeding

The system SHALL provide development data.

#### Scenario: Development setup
- GIVEN a fresh database
- WHEN running the seed script
- THEN a test user is created
- AND sample data is available for development

## Relationships

- User owns Projects (1:N)
- Project has GitRepositories (1:N)
- User has SSHKeys (1:N)
- User has UserConfig (1:1)
- Project optionally has default SSHKey (N:1)

## Dependencies

- PostgreSQL 15+
- SQLAlchemy 2.0+
- asyncpg
- Alembic

## Quality Gates

- `pytest` must pass
- `mypy .` must pass
- `ruff check .` must pass
- All migrations run successfully
- Models use SQLAlchemy 2.0 async style