docs: comprehensive documentation overhaul

Add complete documentation structure: - Frontend architecture documentation - Database schema documentation - Deployment guides (Docker, Traefik, Authentik, Environment) - Development guides (Setup, Testing, Contributing, Quality Gates) - Deployment architecture documentation - Updated docs README with complete navigation All new features and APIs are now documented. Quality gates: docs only, no code changes
2026-05-19 14:18:20 +02:00
parent 6807f449b7
commit 83f94b1f09
31 changed files with 5498 additions and 0 deletions
@@ -0,0 +1,212 @@
+# Backend Architecture
+
+## Overview
+
+The Headquarter backend is built with **FastAPI** and follows a layered architecture pattern.
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                         FastAPI App                          │
+├─────────────────────────────────────────────────────────────┤
+│  Middleware: CORS → Request Logging → Exception Logging      │
+├─────────────────────────────────────────────────────────────┤
+│  API Layer (src/api/)                                        │
+│  ┌─────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐          │
+│  │  Auth   │ │ Projects │ │ Users  │ │   Git    │          │
+│  │ Routes  │ │ Routes   │ │ Routes │ │ Repos    │          │
+│  └────┬────┘ └────┬─────┘ └───┬────┘ └────┬─────┘          │
+├───────┼───────────┼───────────┼───────────┼─────────────────┤
+│       │           │           │           │                  │
+│  Auth │  Project  │   User    │   Git     │                  │
+│ Layer │  Service  │  Service  │ Service   │                  │
+│       │           │           │           │                  │
+├───────┴───────────┴───────────┴───────────┴─────────────────┤
+│  Data Layer                                                  │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                   │
+│  │  Models  │  │ Database │  │   Config │                   │
+│  │(SQLAlch) │  │(AsyncPG) │  │(Pydantic)│                   │
+│  └──────────┘  └──────────┘  └──────────┘                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Directory Structure
+
+```
+src/
+├── api/                    # API Routes
+│   ├── auth.py            # Authentication endpoints
+│   ├── projects.py        # Project endpoints
+│   ├── git_repositories.py # Repository endpoints
+│   ├── users.py           # User endpoints
+│   ├── tool_types.py      # Tool type endpoints
+│   ├── ssh_keys.py        # SSH key endpoints
+│   └── dashboard.py       # Dashboard endpoints
+├── auth/                   # Authentication
+│   ├── session.py         # Session management
+│   ├── oidc.py            # OAuth2 client
+│   ├── dependencies.py    # Auth dependencies
+│   └── cookies.py         # Cookie utilities
+├── models/                 # Database Models
+│   ├── user.py            # User model
+│   ├── project.py         # Project model
+│   ├── git_repository.py  # Repository model
+│   ├── tool_type.py       # Tool type model
+│   ├── ssh_key.py         # SSH key model
+│   └── user_config.py     # User config model
+├── utils/                  # Utilities
+│   ├── git_url_parser.py  # URL parsing
+│   ├── git_files.py       # Git file operations
+│   └── git_history.py     # Git history operations
+├── config.py              # Configuration
+├── database.py            # Database setup
+└── main.py                # Application entry point
+```
+
+## Layers
+
+### 1. API Layer (`src/api/`)
+
+**Responsibilities:**
+- Define HTTP endpoints
+- Parse request parameters
+- Return HTTP responses
+- Use dependencies for auth and DB
+
+**Pattern:**
+```python
+@router.get("/projects")
+async def list_projects(
+    session: AsyncSession = Depends(get_db_session),
+    user_id: str = Depends(get_current_user_id),
+):
+    # Call service layer
+    projects = await project_service.list(session, user_id)
+    return projects
+```
+
+### 2. Auth Layer (`src/auth/`)
+
+**Responsibilities:**
+- Session management (create, verify, expire)
+- OAuth2 flow (login, callback)
+- User authentication dependencies
+
+**Key Components:**
+- `session.py`: HMAC-SHA256 signed cookies
+- `oidc.py`: OAuth2 token exchange
+- `dependencies.py`: FastAPI dependencies for auth
+
+### 3. Data Layer (`src/models/`, `src/database.py`)
+
+**Responsibilities:**
+- Database schema definition
+- Async database sessions
+- Connection management
+
+**Technology:**
+- SQLAlchemy 2.0 with async support
+- asyncpg driver for PostgreSQL
+- Alembic for migrations
+
+### 4. Utility Layer (`src/utils/`)
+
+**Responsibilities:**
+- Git operations (file browsing, history)
+- URL parsing
+- Helper functions
+
+## Data Flow
+
+### Request Lifecycle
+
+```
+1. Request arrives at FastAPI
+2. Middleware processes (CORS, logging)
+3. Auth dependency verifies session
+4. Route handler processes request
+5. Database session executes queries
+6. Response returned to client
+```
+
+### Authentication Flow
+
+```
+1. User clicks login
+2. Backend redirects to Authentik
+3. User authenticates
+4. Authentik redirects with code
+5. Backend exchanges code for token
+6. Backend fetches user info
+7. Backend creates session cookie
+8. User is authenticated
+```
+
+## Dependencies
+
+### Database Session
+
+```python
+async def get_db_session() -> AsyncGenerator[AsyncSession, None]:
+    async with SessionLocal() as session:
+        yield session
+```
+
+### Current User
+
+```python
+async def get_current_user_id(
+    request: Request,
+    settings: Settings = Depends(get_settings),
+) -> str:
+    # Verify session cookie
+    # Return user_id
+```
+
+## Configuration
+
+Configuration is managed via Pydantic Settings:
+
+```python
+class Settings(BaseSettings):
+    app_env: str = "development"
+    database_url: str = "..."
+    authentik_domain: str = "..."
+    # ...
+```
+
+Environment variables are automatically loaded from `.env` files.
+
+## Error Handling
+
+Errors are handled at multiple levels:
+
+1. **Validation**: Pydantic validates request bodies
+2. **HTTP Exceptions**: FastAPI HTTPException for client errors
+3. **Middleware**: ExceptionLoggingMiddleware logs server errors
+4. **Database**: SQLAlchemy errors converted to HTTP responses
+
+## Testing
+
+- **Unit tests**: SQLite in-memory database
+- **Integration tests**: PostgreSQL with transaction rollback
+- **Fixtures**: Shared in `conftest.py`
+
+## Technology Stack
+
+| Component | Technology | Version |
+|-----------|-----------|---------|
+| Web Framework | FastAPI | ^0.104 |
+| ORM | SQLAlchemy | ^2.0 |
+| Database Driver | asyncpg | ^0.29 |
+| Validation | Pydantic | ^2.0 |
+| Migrations | Alembic | ^1.12 |
+| HTTP Client | httpx | ^0.25 |
+| Testing | pytest | ^7.4 |
+
+## Related Documentation
+
+- [Database Schema](database.md)
+- [Frontend Architecture](../frontend.md)
+- [API Documentation](../api/)