Files

T

alex e7819bfc82 feat: implement docker infrastructure (US-001)

- Add docker-compose.yml with postgres, redis, api, and web services
- Add multi-stage Dockerfile for API (Python 3.11)
- Add multi-stage Dockerfile for web (Node.js 20 + nginx)
- Add Makefile with common development commands
- Add .env.example with all required environment variables
- Add placeholder pyproject.toml and package.json for builds
- Configure health checks for all services
- Setup persistent volumes for postgres, redis, and repos
- Run services as non-root users

2026-05-16 17:44:39 +00:00

3.1 KiB

Raw Permalink 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 Permalink Blame History