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
parent 212d072417
commit e7819bfc82
246 changed files with 3625 additions and 17311 deletions
@@ -0,0 +1,127 @@
+# 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