alex
e7819bfc82
- 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
128 lines
3.1 KiB
Markdown
128 lines
3.1 KiB
Markdown
# 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
|