Files

T

Developer c8db6ce933 fix: disable native touch panning on mobile terminal and archive specs

- Change mobile terminal CSS to use touch-action: none and
  overscroll-behavior: none so the custom touch handler owns swipes
- Archive completed/partial OpenSpec specs to
  openspec/changes/archive/2026-06-14-completed-specs-archive/
- Regenerate project maps

Quality gates: npm run typecheck, npm run lint (apps/web)

2026-06-14 18:07:01 +00:00

3.1 KiB

Raw Blame History

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

3.1 KiB Raw Blame History