Merge branch 'main' into codex/implement-web-vitals-tracking-and-api-jt9zi9

Author: shayancoin

.github/workflows/ci.yml

@@ -102,3 +102,76 @@ jobs:
 
     - name: Build
       run: npm run build
+
+  performance-budget:
+    runs-on: ubuntu-latest
+    needs:
+      - frontend-tests
+    env:
+      PERF_BUDGET_HEADLESS: 'true'
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
+
+      - name: Set up Node.js
+        uses: actions/setup-node@0a44ba78451273a1ed8ac2fee4e347c72dfd377f
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: ./frontend/package-lock.json
+
+      - name: Install dependencies
+        working-directory: ./frontend
+        run: npm ci
+
+      - name: Start application stack
+        run: |
+          docker compose -f docker-compose.dev.yml up -d --build
+
+      - name: Wait for API
+        run: |
+          for i in {1..60}; do curl -sf http://localhost:8000/healthcheck && break || sleep 2; done
+
+      - name: Wait for Frontend
+        run: |
+          for i in {1..60}; do curl -sf http://localhost:3000/models/manifest.json && break || sleep 2; done
+
+      - name: Run performance budget checks
+        working-directory: ./frontend
+        env:
+          PERF_BUDGET_OUTPUT_DIR: ../test-results/perf
+        run: npm run perf:budget
+
+      - name: Upload performance budget report
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: perf-budget
+          path: test-results/perf
+
+      - name: Shutdown stack
+        if: always()
+        run: |
+          docker compose -f docker-compose.dev.yml down
+
+  observability-budgets:
+    runs-on: ubuntu-latest
+    needs:
+      - performance-budget
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
+
+      - name: Set up Python
+        uses: actions/setup-python@e797f83bcb11b83ae66e0230d6156d7c80228e7c
+        with:
+          python-version: '3.12'
+
+      - name: Install dependencies
+        run: pip install pyyaml
+
+      - name: Check observability budgets
+        env:
+          PROMETHEUS_URL: ${{ secrets.PROMETHEUS_URL }}
+          PROMETHEUS_BEARER_TOKEN: ${{ secrets.PROMETHEUS_BEARER_TOKEN }}
+          TEMPO_URL: ${{ secrets.TEMPO_URL }}
+          TEMPO_BEARER_TOKEN: ${{ secrets.TEMPO_BEARER_TOKEN }}
+        run: python tools/ci/check_observability_budgets.py --config observability-budgets.yml

.github/workflows/perf.yml

@@ -0,0 +1,75 @@
+name: perf
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+on:
+  workflow_dispatch:
+
+jobs:
+  playwright-perf:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    defaults:
+      run:
+        working-directory: ./frontend
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8
+
+      - name: Set up Node.js
+        uses: actions/setup-node@0a44ba78451273a1ed8ac2fee4e347c72dfd377f
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: ./frontend/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Build application
+        run: npm run build
+
+      - name: Start application
+        run: |
+          npm run start -- --hostname 0.0.0.0 --port 3000 &
+          echo $! > ../.next-server-pid
+          for i in {1..60}; do
+            if curl -sSf http://127.0.0.1:3000 > /dev/null; then
+              break
+            fi
+            sleep 2
+          done
+          if ! curl -sSf http://127.0.0.1:3000 > /dev/null; then
+            echo "Application failed to start" >&2
+            exit 1
+          fi
+
+      - name: Run Playwright perf tests
+        env:
+          BASE_URL: http://127.0.0.1:3000
+        run: npx playwright test --reporter=line,html
+
+      - name: Stop application
+        if: always()
+        run: |
+          if [ -f ../.next-server-pid ]; then
+            kill $(cat ../.next-server-pid) || true
+            rm -f ../.next-server-pid
+          fi
+
+      - name: Upload Playwright artifacts
+        if: always()
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: playwright-perf-artifacts
+          path: |
+            frontend/playwright-report
+            frontend/test-results
+          if-no-files-found: warn

.gitignore

@@ -36,6 +36,7 @@ yarn-error.log*
 .next/
 out/
 .cache/
+artifacts/
 
 # Env files (keep example)
 .env

README.md

@@ -102,6 +102,16 @@ The frontend uses Next.js App Router architecture:
 docker compose --env-file .env.development -f docker-compose.dev.yml up
 ```
 
+To launch the observability stack alongside your application, start a second
+Compose project in a separate terminal:
+
+```bash
+docker compose -f docker-compose.observability.yml up
+```
+
+This brings up Prometheus, Grafana, Loki, Tempo, and the OpenTelemetry
+Collector with their configuration mounted from the `ops/` directory.
+
 ### Production
 
 ```bash

artifacts/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

backend/README.md

@@ -25,7 +25,9 @@ docker compose --env-file .env.development -f docker-compose.dev.yml up backend-
 
 The backend expects the following environment variables (or entries in `.env.development`):
 
+- `API_WRITE_TOKEN` – Bearer token required for privileged sync and admin endpoints.
 - `HYGRAPH_WEBHOOK_SECRET` – Shared secret used to validate incoming Hygraph webhook signatures.
+- `API_WRITE_TOKEN` – Bearer token required for privileged sync endpoints such as `/api/sync/hygraph/pull`.
 
 ## Project Structure
 

backend/api/config.py

@@ -1,7 +1,7 @@
 """Configuration settings for the FastAPI application."""
 
-from functools import lru_cache
-from typing import Any, Dict
+import os
+from typing import Any, Dict, Optional
 
 from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -16,6 +16,11 @@ class Settings(BaseSettings):
         default=3000,
         description="Port for the frontend service",
     )
+    api_write_token: str | None = Field(
+        default=None,
+        description="Bearer token required for write-protected API routes.",
+        repr=False,
+    )
 
     # Database and integration settings
     database_url: str = Field(
@@ -34,6 +39,11 @@ class Settings(BaseSettings):
         default="",
         description="Hygraph access token",
     )
+    api_write_token: str = Field(
+        default="",
+        description="Bearer token required for privileged write routes",
+        repr=False,
+    )
     hygraph_webhook_secret: str = Field(
         description=(
             "Shared secret used to verify Hygraph webhook signatures."
@@ -42,6 +52,14 @@ class Settings(BaseSettings):
         min_length=1,
         repr=False,
     )
+    api_write_token: str | None = Field(
+        default=None,
+        description=(
+            "Bearer token required for privileged API write operations."
+            " Provide via the API_WRITE_TOKEN environment variable."
+        ),
+        repr=False,
+    )
 
     model_config = SettingsConfigDict(
         env_file=".env.development",
@@ -61,12 +79,31 @@ def _validate_hygraph_webhook_secret(cls, value: str) -> str:
             )
         return value.strip()
 
+    @field_validator("api_write_token")
+    @classmethod
+    def _normalize_api_write_token(cls, value: str | None) -> str | None:
+        """Normalize optional API write tokens."""
+
+        if value is None:
+            return None
+        value = value.strip()
+        return value or None
+
+
+_SETTINGS_CACHE: Optional[Settings] = None
+_LAST_SECRET: Optional[str] = None
+
 
-@lru_cache()
 def get_settings() -> Settings:
-    """Return a cached instance of :class:`Settings`."""
+    """Return a cached instance of :class:`Settings`, refreshing on secret changes."""
 
-    return Settings()
+    global _SETTINGS_CACHE, _LAST_SECRET
+    current_secret = os.getenv("HYGRAPH_WEBHOOK_SECRET")
+    if _SETTINGS_CACHE is None or _LAST_SECRET != current_secret:
+        settings = Settings()
+        _SETTINGS_CACHE = settings
+        _LAST_SECRET = settings.hygraph_webhook_secret
+    return _SETTINGS_CACHE
 
 
 def get_fastapi_settings() -> Dict[str, Any]:

backend/api/db.py

@@ -29,7 +29,10 @@ def _normalize_postgres_url(url: str) -> str:
 
 def get_engine_url() -> str:
     """Resolve the database URL from env or settings with sane defaults."""
+    # Use the cached settings instance instead of instantiating ``Settings``
+    # directly so configuration is read a single time across the app.
     settings = get_settings()
+    # ``get_settings`` returns the cached Settings instance from api.config.
     url = os.getenv("DATABASE_URL", settings.database_url)
     if url.startswith("sqlite"):
         return url
@@ -56,4 +59,4 @@ def get_db() -> Generator:
     try:
         yield db
     finally:
-        db.close()
+        db.close()