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,365 @@
+# Quality Gates
+
+## Overview
+
+All code changes must pass quality gates before being merged. These gates ensure code consistency, type safety, and prevent common issues.
+
+## Backend Quality Gates
+
+### 1. Code Formatting (ruff)
+
+**Purpose**: Enforce consistent code style
+
+```bash
+cd apps/api
+ruff check src/ tests/
+ruff format src/ tests/
+```
+
+**Configuration** (`pyproject.toml`):
+```toml
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+select = ["E", "F", "I", "W", "UP"]
+ignore = ["E501"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+```
+
+**Pre-commit hook**:
+```bash
+# Install pre-commit
+pip install pre-commit
+pre-commit install
+
+# Run manually
+pre-commit run --all-files
+```
+
+### 2. Type Checking (mypy)
+
+**Purpose**: Catch type errors before runtime
+
+```bash
+cd apps/api
+mypy src/
+```
+
+**Configuration** (`pyproject.toml`):
+```toml
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_ignores = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+```
+
+**Common issues**:
+- Missing type hints on function parameters
+- Returning wrong type
+- None checks needed
+
+### 3. Unit Tests (pytest)
+
+**Purpose**: Verify functionality works as expected
+
+```bash
+cd apps/api
+pytest -v
+```
+
+**Requirements**:
+- All tests must pass
+- New code should have tests
+- Coverage should not decrease
+
+### 4. Security Checks
+
+**Bandit** (security linter):
+```bash
+bandit -r src/
+```
+
+**Safety** (dependency vulnerabilities):
+```bash
+safety check
+```
+
+## Frontend Quality Gates
+
+### 1. Type Checking (TypeScript)
+
+**Purpose**: Catch type errors at build time
+
+```bash
+cd apps/web
+npm run typecheck
+```
+
+**Configuration** (`tsconfig.json`):
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  }
+}
+```
+
+### 2. Linting (ESLint)
+
+**Purpose**: Enforce code style and catch issues
+
+```bash
+cd apps/web
+npm run lint
+npm run lint:fix
+```
+
+**Configuration** (`.eslintrc.cjs`):
+```javascript
+module.exports = {
+  root: true,
+  env: { browser: true, es2020: true },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended',
+    'plugin:react-hooks/recommended',
+  ],
+  parser: '@typescript-eslint/parser',
+  plugins: ['react-refresh'],
+  rules: {
+    'react-refresh/only-export-components': [
+      'warn',
+      { allowConstantExport: true },
+    ],
+  },
+}
+```
+
+### 3. Build Check
+
+**Purpose**: Ensure production build succeeds
+
+```bash
+cd apps/web
+npm run build
+```
+
+**Requirements**:
+- No TypeScript errors
+- No build warnings
+- Bundle size reasonable
+
+### 4. Unit Tests (Vitest)
+
+```bash
+cd apps/web
+npm run test
+```
+
+**Requirements**:
+- All tests pass
+- No test failures
+- Coverage maintained
+
+## Running All Gates
+
+### Backend
+
+```bash
+cd apps/api
+
+# Run all gates
+ruff check src/ tests/ && \
+mypy src/ && \
+pytest
+
+# Or use Makefile
+make lint      # ruff + mypy
+make test      # pytest
+make check     # All backend gates
+```
+
+### Frontend
+
+```bash
+cd apps/web
+
+# Run all gates
+npm run lint && \
+npm run typecheck && \
+npm run test && \
+npm run build
+
+# Or use package.json scripts
+npm run check  # All frontend gates
+```
+
+### Full Project
+
+```bash
+# From root
+make check-all  # Run all backend and frontend gates
+```
+
+## Continuous Integration
+
+All quality gates run automatically on:
+- Every Pull Request
+- Every push to main branch
+
+**CI Pipeline**:
+```yaml
+stages:
+  - lint
+  - test
+  - build
+
+backend-lint:
+  stage: lint
+  script:
+    - cd apps/api && ruff check src/ tests/
+    - cd apps/api && mypy src/
+
+backend-test:
+  stage: test
+  script:
+    - cd apps/api && pytest -v
+
+frontend-lint:
+  stage: lint
+  script:
+    - cd apps/web && npm run lint
+    - cd apps/web && npm run typecheck
+
+frontend-test:
+  stage: test
+  script:
+    - cd apps/web && npm run test
+
+frontend-build:
+  stage: build
+  script:
+    - cd apps/web && npm run build
+```
+
+## Fixing Common Issues
+
+### Backend
+
+**ruff: Line too long**
+```python
+# Bad
+result = some_very_long_function_name(with_many_parameters, that_make_the_line_too_long)
+
+# Good
+result = some_very_long_function_name(
+    with_many_parameters, 
+    that_make_the_line_too_long,
+)
+```
+
+**mypy: Missing return type**
+```python
+# Bad
+def get_user(user_id):
+    return User.query.get(user_id)
+
+# Good
+def get_user(user_id: str) -> User | None:
+    return User.query.get(user_id)
+```
+
+### Frontend
+
+**TypeScript: Implicit any**
+```typescript
+// Bad
+function processData(data) {
+  return data.map(item => item.name);
+}
+
+// Good
+function processData(data: DataItem[]) {
+  return data.map(item => item.name);
+}
+```
+
+**ESLint: Unused variable**
+```typescript
+// Bad
+const [count, setCount] = useState(0);
+// count is never used
+
+// Good
+const [count] = useState(0);
+// Or remove if not needed
+```
+
+## IDE Integration
+
+### VS Code
+
+**Settings** (`.vscode/settings.json`):
+```json
+{
+  "python.linting.enabled": true,
+  "python.linting.mypyEnabled": true,
+  "python.formatting.provider": "ruff",
+  "editor.formatOnSave": true,
+  "editor.codeActionsOnSave": {
+    "source.fixAll.eslint": true
+  }
+}
+```
+
+### PyCharm
+
+1. **File** → **Settings** → **Tools** → **External Tools**
+2. Add ruff and mypy as external tools
+3. Set up pre-commit hooks
+
+## Pre-commit Hooks
+
+`.pre-commit-config.yaml`:
+```yaml
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.1.0
+    hooks:
+      - id: ruff
+        args: [--fix, --exit-non-zero-on-fix]
+      - id: ruff-format
+  
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.7.0
+    hooks:
+      - id: mypy
+        additional_dependencies: [types-all]
+  
+  - repo: local
+    hooks:
+      - id: frontend-lint
+        name: Frontend Lint
+        entry: bash -c 'cd apps/web && npm run lint'
+        language: system
+        files: ^apps/web/
+```
+
+## Resources
+
+- [ruff Documentation](https://docs.astral.sh/ruff/)
+- [mypy Documentation](https://mypy.readthedocs.io/)
+- [ESLint Documentation](https://eslint.org/)
+- [TypeScript Handbook](https://www.typescriptlang.org/docs/)