ci: Bump version to 0.12.15 [skip ci]

docs/adr/0015-application-performance-monitoring-and-error-tracking.md

@@ -1,324 +0,0 @@
-# ADR-015: Application Performance Monitoring (APM) and Error Tracking
-
-**Date**: 2025-12-12
-
-**Status**: Accepted
-
-**Updated**: 2026-01-11
-
-## Context
-
-While `ADR-004` established structured logging with Pino, the application lacks a high-level, aggregated view of its health, performance, and errors. It's difficult to spot trends, identify slow API endpoints, or be proactively notified of new types of errors.
-
-Key requirements:
-
-1. **Self-hosted**: No external SaaS dependencies for error tracking
-2. **Sentry SDK compatible**: Leverage mature, well-documented SDKs
-3. **Lightweight**: Minimal resource overhead in the dev container
-4. **Production-ready**: Same architecture works on bare-metal production servers
-5. **AI-accessible**: MCP server integration for Claude Code and other AI tools
-
-## Decision
-
-We will implement a self-hosted error tracking stack using **Bugsink** as the Sentry-compatible backend, with the following components:
-
-### 1. Error Tracking Backend: Bugsink
-
-**Bugsink** is a lightweight, self-hosted Sentry alternative that:
-
-- Runs as a single process (no Kafka, Redis, ClickHouse required)
-- Is fully compatible with Sentry SDKs
-- Supports ARM64 and AMD64 architectures
-- Can use SQLite (dev) or PostgreSQL (production)
-
-**Deployment**:
-
-- **Dev container**: Installed as a systemd service inside the container
-- **Production**: Runs as a systemd service on bare-metal, listening on localhost only
-- **Database**: Uses PostgreSQL with a dedicated `bugsink` user and `bugsink` database (same PostgreSQL instance as the main application)
-
-### 2. Backend Integration: @sentry/node
-
-The Express backend will integrate `@sentry/node` SDK to:
-
-- Capture unhandled exceptions before PM2/process manager restarts
-- Report errors with full stack traces and context
-- Integrate with Pino logger for breadcrumbs
-- Track transaction performance (optional)
-
-### 3. Frontend Integration: @sentry/react
-
-The React frontend will integrate `@sentry/react` SDK to:
-
-- Wrap the app in a Sentry Error Boundary
-- Capture unhandled JavaScript errors
-- Report errors with component stack traces
-- Track user session context
-- **Frontend Error Correlation**: The global API client (Axios/Fetch wrapper) MUST intercept 4xx/5xx responses. It MUST extract the `x-request-id` header (if present) and attach it to the Sentry scope as a tag `api_request_id` before re-throwing the error. This allows developers to copy the ID from Sentry and search for it in backend logs.
-
-### 4. Log Aggregation: Logstash
-
-**Logstash** parses application and infrastructure logs, forwarding error patterns to Bugsink:
-
-- **Installation**: Installed inside the dev container (and on bare-metal prod servers)
-- **Inputs**:
-  - Pino JSON logs from the Node.js application
-  - Redis logs (connection errors, memory warnings, slow commands)
-  - PostgreSQL function logs (future - see Implementation Steps)
-- **Filter**: Identifies error-level logs (5xx responses, unhandled exceptions, Redis errors)
-- **Output**: Sends to Bugsink via Sentry-compatible HTTP API
-
-This provides a secondary error capture path for:
-
-- Errors that occur before Sentry SDK initialization
-- Log-based errors that don't throw exceptions
-- Redis connection/performance issues
-- Database function errors and slow queries
-- Historical error analysis from log files
-
-### 5. MCP Server Integration: bugsink-mcp
-
-For AI tool integration (Claude Code, Cursor, etc.), we use the open-source [bugsink-mcp](https://github.com/j-shelfwood/bugsink-mcp) server:
-
-- **No code changes required**: Configurable via environment variables
-- **Capabilities**: List projects, get issues, view events, get stacktraces, manage releases
-- **Configuration**:
-  - `BUGSINK_URL`: Points to Bugsink instance (`http://localhost:8000` for dev, `https://bugsink.projectium.com` for prod)
-  - `BUGSINK_API_TOKEN`: API token from Bugsink (created via Django management command)
-  - `BUGSINK_ORG_SLUG`: Organization identifier (usually "sentry")
-
-**Note:** Despite the name `sentry-selfhosted-mcp` mentioned in earlier drafts of this ADR, the actual MCP server used is `bugsink-mcp` which is specifically designed for Bugsink's API structure.
-
-## Architecture
-
-```text
-┌─────────────────────────────────────────────────────────────────────────┐
-│                      Dev Container / Production Server                   │
-├─────────────────────────────────────────────────────────────────────────┤
-│                                                                          │
-│  ┌──────────────────┐        ┌──────────────────┐                       │
-│  │    Frontend      │        │     Backend      │                       │
-│  │    (React)       │        │    (Express)     │                       │
-│  │  @sentry/react   │        │   @sentry/node   │                       │
-│  └────────┬─────────┘        └────────┬─────────┘                       │
-│           │                           │                                  │
-│           │    Sentry SDK Protocol    │                                  │
-│           └───────────┬───────────────┘                                  │
-│                       │                                                  │
-│                       ▼                                                  │
-│           ┌──────────────────────┐                                       │
-│           │      Bugsink         │                                       │
-│           │   (localhost:8000)   │◄──────────────────┐                   │
-│           │                      │                   │                   │
-│           │  PostgreSQL backend  │                   │                   │
-│           └──────────────────────┘                   │                   │
-│                                                      │                   │
-│           ┌──────────────────────┐                   │                   │
-│           │      Logstash        │───────────────────┘                   │
-│           │   (Log Aggregator)   │   Sentry Output                       │
-│           │                      │                                       │
-│           │  Inputs:             │                                       │
-│           │  - Pino app logs     │                                       │
-│           │  - Redis logs        │                                       │
-│           │  - PostgreSQL (future)                                       │
-│           └──────────────────────┘                                       │
-│                   ▲   ▲   ▲                                              │
-│                   │   │   │                                              │
-│       ┌───────────┘   │   └───────────┐                                  │
-│       │               │               │                                  │
-│  ┌────┴─────┐   ┌─────┴────┐   ┌──────┴─────┐                           │
-│  │  Pino    │   │  Redis   │   │ PostgreSQL │                           │
-│  │  Logs    │   │  Logs    │   │ Logs (TBD) │                           │
-│  └──────────┘   └──────────┘   └────────────┘                           │
-│                                                                          │
-│           ┌──────────────────────┐                                       │
-│           │     PostgreSQL       │                                       │
-│           │  ┌────────────────┐  │                                       │
-│           │  │ flyer_crawler  │  │  (main app database)                  │
-│           │  ├────────────────┤  │                                       │
-│           │  │   bugsink      │  │  (error tracking database)            │
-│           │  └────────────────┘  │                                       │
-│           └──────────────────────┘                                       │
-│                                                                          │
-└─────────────────────────────────────────────────────────────────────────┘
-
-External (Developer Machine):
-┌──────────────────────────────────────┐
-│  Claude Code / Cursor / VS Code      │
-│  ┌────────────────────────────────┐  │
-│  │  bugsink-mcp                   │  │
-│  │  (MCP Server)                  │  │
-│  │                                │  │
-│  │  BUGSINK_URL=http://localhost:8000
-│  │  BUGSINK_API_TOKEN=...         │  │
-│  │  BUGSINK_ORG_SLUG=...          │  │
-│  └────────────────────────────────┘  │
-└──────────────────────────────────────┘
-```
-
-## Configuration
-
-### Environment Variables
-
-| Variable           | Description                    | Default (Dev)              |
-| ------------------ | ------------------------------ | -------------------------- |
-| `BUGSINK_DSN`      | Sentry-compatible DSN for SDKs | Set after project creation |
-| `BUGSINK_ENABLED`  | Enable/disable error reporting | `true`                     |
-| `BUGSINK_BASE_URL` | Bugsink web UI URL (internal)  | `http://localhost:8000`    |
-
-### PostgreSQL Setup
-
-```sql
--- Create dedicated Bugsink database and user
-CREATE USER bugsink WITH PASSWORD 'bugsink_dev_password';
-CREATE DATABASE bugsink OWNER bugsink;
-GRANT ALL PRIVILEGES ON DATABASE bugsink TO bugsink;
-```
-
-### Bugsink Configuration
-
-```bash
-# Environment variables for Bugsink service
-SECRET_KEY=<random-50-char-string>
-DATABASE_URL=postgresql://bugsink:bugsink_dev_password@localhost:5432/bugsink
-BASE_URL=http://localhost:8000
-PORT=8000
-```
-
-### Logstash Pipeline
-
-```conf
-# /etc/logstash/conf.d/bugsink.conf
-
-# === INPUTS ===
-input {
-  # Pino application logs
-  file {
-    path => "/app/logs/*.log"
-    codec => json
-    type => "pino"
-    tags => ["app"]
-  }
-
-  # Redis logs
-  file {
-    path => "/var/log/redis/*.log"
-    type => "redis"
-    tags => ["redis"]
-  }
-
-  # PostgreSQL logs (for function logging - future)
-  # file {
-  #   path => "/var/log/postgresql/*.log"
-  #   type => "postgres"
-  #   tags => ["postgres"]
-  # }
-}
-
-# === FILTERS ===
-filter {
-  # Pino error detection (level 50 = error, 60 = fatal)
-  if [type] == "pino" and [level] >= 50 {
-    mutate { add_tag => ["error"] }
-  }
-
-  # Redis error detection
-  if [type] == "redis" {
-    grok {
-      match => { "message" => "%{POSINT:pid}:%{WORD:role} %{MONTHDAY} %{MONTH} %{TIME} %{WORD:loglevel} %{GREEDYDATA:redis_message}" }
-    }
-    if [loglevel] in ["WARNING", "ERROR"] {
-      mutate { add_tag => ["error"] }
-    }
-  }
-
-  # PostgreSQL function error detection (future)
-  # if [type] == "postgres" {
-  #   # Parse PostgreSQL log format and detect ERROR/FATAL levels
-  # }
-}
-
-# === OUTPUT ===
-output {
-  if "error" in [tags] {
-    http {
-      url => "http://localhost:8000/api/store/"
-      http_method => "post"
-      format => "json"
-      # Sentry envelope format
-    }
-  }
-}
-```
-
-## Implementation Steps
-
-1. **Update Dockerfile.dev**:
-   - Install Bugsink (pip package or binary)
-   - Install Logstash (Elastic APT repository)
-   - Add systemd service files for both
-
-2. **PostgreSQL initialization**:
-   - Add Bugsink user/database creation to `sql/00-init-extensions.sql`
-
-3. **Backend SDK integration**:
-   - Install `@sentry/node`
-   - Initialize in `server.ts` before Express app
-   - Configure error handler middleware integration
-
-4. **Frontend SDK integration**:
-   - Install `@sentry/react`
-   - Wrap `App` component with `Sentry.ErrorBoundary`
-   - Configure in `src/index.tsx`
-
-5. **Environment configuration**:
-   - Add Bugsink variables to `src/config/env.ts`
-   - Update `.env.example` and `compose.dev.yml`
-
-6. **Logstash configuration**:
-   - Create pipeline config for Pino → Bugsink
-   - Configure Pino to write to log file in addition to stdout
-   - Configure Redis log monitoring (connection errors, slow commands)
-
-7. **MCP server documentation**:
-   - Document `bugsink-mcp` setup in CLAUDE.md
-
-8. **PostgreSQL function logging** (future):
-   - Configure PostgreSQL to log function execution errors
-   - Add Logstash input for PostgreSQL logs
-   - Define filter rules for function-level error detection
-   - _Note: Ask for implementation details when this step is reached_
-
-## Consequences
-
-### Positive
-
-- **Full observability**: Aggregated view of errors, trends, and performance
-- **Self-hosted**: No external SaaS dependencies or subscription costs
-- **SDK compatibility**: Leverages mature Sentry SDKs with excellent documentation
-- **AI integration**: MCP server enables Claude Code to query and analyze errors
-- **Unified architecture**: Same setup works in dev container and production
-- **Lightweight**: Bugsink runs in a single process, unlike full Sentry (16GB+ RAM)
-
-### Negative
-
-- **Additional services**: Bugsink and Logstash add complexity to the container
-- **PostgreSQL overhead**: Additional database for error tracking
-- **Initial setup**: Requires configuration of multiple components
-- **Logstash learning curve**: Pipeline configuration requires Logstash knowledge
-
-## Alternatives Considered
-
-1. **Full Sentry self-hosted**: Rejected due to complexity (Kafka, Redis, ClickHouse, 16GB+ RAM minimum)
-2. **GlitchTip**: Considered, but Bugsink is lighter weight and easier to deploy
-3. **Sentry SaaS**: Rejected due to self-hosted requirement
-4. **Custom error aggregation**: Rejected in favor of proven Sentry SDK ecosystem
-
-## References
-
-- [Bugsink Documentation](https://www.bugsink.com/docs/)
-- [Bugsink Docker Install](https://www.bugsink.com/docs/docker-install/)
-- [@sentry/node Documentation](https://docs.sentry.io/platforms/javascript/guides/node/)
-- [@sentry/react Documentation](https://docs.sentry.io/platforms/javascript/guides/react/)
-- [bugsink-mcp](https://github.com/j-shelfwood/bugsink-mcp)
-- [Logstash Reference](https://www.elastic.co/guide/en/logstash/current/index.html)

docs/adr/0015-error-tracking-and-observability.md

@@ -0,0 +1,272 @@
+# ADR-015: Error Tracking and Observability
+
+**Date**: 2025-12-12
+
+**Status**: Accepted (Fully Implemented)
+
+**Updated**: 2026-01-26 (user context integration completed)
+
+**Related**: [ADR-056](./0056-application-performance-monitoring.md) (Application Performance Monitoring)
+
+## Context
+
+While ADR-004 established structured logging with Pino, the application lacks a high-level, aggregated view of its health and errors. It's difficult to spot trends, identify recurring issues, or be proactively notified of new types of errors.
+
+Key requirements:
+
+1. **Self-hosted**: No external SaaS dependencies for error tracking
+2. **Sentry SDK compatible**: Leverage mature, well-documented SDKs
+3. **Lightweight**: Minimal resource overhead in the dev container
+4. **Production-ready**: Same architecture works on bare-metal production servers
+5. **AI-accessible**: MCP server integration for Claude Code and other AI tools
+
+**Note**: Application Performance Monitoring (APM) and distributed tracing are covered separately in [ADR-056](./0056-application-performance-monitoring.md).
+
+## Decision
+
+We implement a self-hosted error tracking stack using **Bugsink** as the Sentry-compatible backend, with the following components:
+
+### 1. Error Tracking Backend: Bugsink
+
+**Bugsink** is a lightweight, self-hosted Sentry alternative that:
+
+- Runs as a single process (no Kafka, Redis, ClickHouse required)
+- Is fully compatible with Sentry SDKs
+- Supports ARM64 and AMD64 architectures
+- Can use SQLite (dev) or PostgreSQL (production)
+
+**Deployment**:
+
+- **Dev container**: Installed as a systemd service inside the container
+- **Production**: Runs as a systemd service on bare-metal, listening on localhost only
+- **Database**: Uses PostgreSQL with a dedicated `bugsink` user and `bugsink` database (same PostgreSQL instance as the main application)
+
+### 2. Backend Integration: @sentry/node
+
+The Express backend integrates `@sentry/node` SDK to:
+
+- Capture unhandled exceptions before PM2/process manager restarts
+- Report errors with full stack traces and context
+- Integrate with Pino logger for breadcrumbs
+- Filter errors by severity (only 5xx errors sent by default)
+
+### 3. Frontend Integration: @sentry/react
+
+The React frontend integrates `@sentry/react` SDK to:
+
+- Wrap the app in an Error Boundary for graceful error handling
+- Capture unhandled JavaScript errors
+- Report errors with component stack traces
+- Filter out browser extension errors
+- **Frontend Error Correlation**: The global API client intercepts 4xx/5xx responses and can attach the `x-request-id` header to Sentry scope for correlation with backend logs
+
+### 4. Log Aggregation: Logstash
+
+**Logstash** parses application and infrastructure logs, forwarding error patterns to Bugsink:
+
+- **Installation**: Installed inside the dev container (and on bare-metal prod servers)
+- **Inputs**:
+  - Pino JSON logs from the Node.js application (PM2 managed)
+  - Redis logs (connection errors, memory warnings, slow commands)
+  - PostgreSQL function logs (via `fn_log()` - see ADR-050)
+  - NGINX access/error logs
+- **Filter**: Identifies error-level logs (5xx responses, unhandled exceptions, Redis errors)
+- **Output**: Sends to Bugsink via Sentry-compatible HTTP API
+
+This provides a secondary error capture path for:
+
+- Errors that occur before Sentry SDK initialization
+- Log-based errors that don't throw exceptions
+- Redis connection/performance issues
+- Database function errors and slow queries
+- Historical error analysis from log files
+
+### 5. MCP Server Integration: bugsink-mcp
+
+For AI tool integration (Claude Code, Cursor, etc.), we use the open-source [bugsink-mcp](https://github.com/j-shelfwood/bugsink-mcp) server:
+
+- **No code changes required**: Configurable via environment variables
+- **Capabilities**: List projects, get issues, view events, get stacktraces, manage releases
+- **Configuration**:
+  - `BUGSINK_URL`: Points to Bugsink instance (`http://localhost:8000` for dev, `https://bugsink.projectium.com` for prod)
+  - `BUGSINK_API_TOKEN`: API token from Bugsink (created via Django management command)
+  - `BUGSINK_ORG_SLUG`: Organization identifier (usually "sentry")
+
+## Architecture
+
+```text
++---------------------------------------------------------------------------+
+|                      Dev Container / Production Server                     |
++---------------------------------------------------------------------------+
+|                                                                            |
+|  +------------------+        +------------------+                          |
+|  |    Frontend      |        |     Backend      |                          |
+|  |    (React)       |        |    (Express)     |                          |
+|  |  @sentry/react   |        |   @sentry/node   |                          |
+|  +--------+---------+        +--------+---------+                          |
+|           |                           |                                    |
+|           |    Sentry SDK Protocol    |                                    |
+|           +-----------+---------------+                                    |
+|                       |                                                    |
+|                       v                                                    |
+|           +----------------------+                                         |
+|           |      Bugsink         |                                         |
+|           |   (localhost:8000)   |<------------------+                     |
+|           |                      |                   |                     |
+|           |  PostgreSQL backend  |                   |                     |
+|           +----------------------+                   |                     |
+|                                                      |                     |
+|           +----------------------+                   |                     |
+|           |      Logstash        |-------------------+                     |
+|           |   (Log Aggregator)   |   Sentry Output                         |
+|           |                      |                                         |
+|           |  Inputs:             |                                         |
+|           |  - PM2/Pino logs     |                                         |
+|           |  - Redis logs        |                                         |
+|           |  - PostgreSQL logs   |                                         |
+|           |  - NGINX logs        |                                         |
+|           +----------------------+                                         |
+|                   ^   ^   ^   ^                                            |
+|                   |   |   |   |                                            |
+|       +-----------+   |   |   +-----------+                                |
+|       |               |   |               |                                |
+|  +----+-----+   +-----+----+   +-----+----+   +-----+----+                 |
+|  |  PM2     |   |  Redis   |   | PostgreSQL|   |  NGINX  |                 |
+|  |  Logs    |   |  Logs    |   |   Logs    |   |  Logs   |                 |
+|  +----------+   +----------+   +-----------+   +---------+                 |
+|                                                                            |
+|           +----------------------+                                         |
+|           |     PostgreSQL       |                                         |
+|           |  +----------------+  |                                         |
+|           |  | flyer_crawler  |  |  (main app database)                    |
+|           |  +----------------+  |                                         |
+|           |  |   bugsink      |  |  (error tracking database)              |
+|           |  +----------------+  |                                         |
+|           +----------------------+                                         |
+|                                                                            |
++---------------------------------------------------------------------------+
+
+External (Developer Machine):
++--------------------------------------+
+|  Claude Code / Cursor / VS Code      |
+|  +--------------------------------+  |
+|  |  bugsink-mcp                   |  |
+|  |  (MCP Server)                  |  |
+|  |                                |  |
+|  |  BUGSINK_URL=http://localhost:8000
+|  |  BUGSINK_API_TOKEN=...         |  |
+|  |  BUGSINK_ORG_SLUG=...          |  |
+|  +--------------------------------+  |
++--------------------------------------+
+```
+
+## Implementation Status
+
+### Completed
+
+- [x] Bugsink installed and configured in dev container
+- [x] PostgreSQL `bugsink` database and user created
+- [x] `@sentry/node` SDK integrated in backend (`src/services/sentry.server.ts`)
+- [x] `@sentry/react` SDK integrated in frontend (`src/services/sentry.client.ts`)
+- [x] ErrorBoundary component created (`src/components/ErrorBoundary.tsx`)
+- [x] ErrorBoundary wrapped around app (`src/providers/AppProviders.tsx`)
+- [x] Logstash pipeline configured for PM2/Pino, Redis, PostgreSQL, NGINX logs
+- [x] MCP server (`bugsink-mcp`) documented and configured
+- [x] Environment variables added to `src/config/env.ts` and frontend `src/config.ts`
+- [x] Browser extension errors filtered in `beforeSend`
+- [x] 5xx error filtering in backend error handler
+
+### Recently Completed (2026-01-26)
+
+- [x] **User context after authentication**: Integrated `setUser()` calls in `AuthProvider.tsx` to associate errors with authenticated users
+  - Called on profile fetch from query (line 44-49)
+  - Called on direct login with profile (line 94-99)
+  - Called on login with profile fetch (line 124-129)
+  - Cleared on logout (line 76-77)
+  - Maps `user_id` → `id`, `email` → `email`, `full_name` → `username`
+
+This completes the error tracking implementation - all errors are now associated with the authenticated user who encountered them, enabling user-specific error analysis and debugging.
+
+## Configuration
+
+### Environment Variables
+
+| Variable             | Description                      | Default (Dev)              |
+| -------------------- | -------------------------------- | -------------------------- |
+| `SENTRY_DSN`         | Sentry-compatible DSN (backend)  | Set after project creation |
+| `VITE_SENTRY_DSN`    | Sentry-compatible DSN (frontend) | Set after project creation |
+| `SENTRY_ENVIRONMENT` | Environment name                 | `development`              |
+| `SENTRY_DEBUG`       | Enable debug logging             | `false`                    |
+| `SENTRY_ENABLED`     | Enable/disable error reporting   | `true`                     |
+
+### PostgreSQL Setup
+
+```sql
+-- Create dedicated Bugsink database and user
+CREATE USER bugsink WITH PASSWORD 'bugsink_dev_password';
+CREATE DATABASE bugsink OWNER bugsink;
+GRANT ALL PRIVILEGES ON DATABASE bugsink TO bugsink;
+```
+
+### Bugsink Configuration
+
+```bash
+# Environment variables for Bugsink service
+SECRET_KEY=<random-50-char-string>
+DATABASE_URL=postgresql://bugsink:bugsink_dev_password@localhost:5432/bugsink
+BASE_URL=http://localhost:8000
+PORT=8000
+```
+
+### Logstash Pipeline
+
+See `docker/logstash/bugsink.conf` for the full pipeline configuration.
+
+Key routing:
+
+| Source          | Bugsink Project |
+| --------------- | --------------- |
+| Backend (Pino)  | Backend API     |
+| Worker (Pino)   | Backend API     |
+| PostgreSQL logs | Backend API     |
+| Vite logs       | Infrastructure  |
+| Redis logs      | Infrastructure  |
+| NGINX logs      | Infrastructure  |
+| Frontend errors | Frontend        |
+
+## Consequences
+
+### Positive
+
+- **Full observability**: Aggregated view of errors and trends
+- **Self-hosted**: No external SaaS dependencies or subscription costs
+- **SDK compatibility**: Leverages mature Sentry SDKs with excellent documentation
+- **AI integration**: MCP server enables Claude Code to query and analyze errors
+- **Unified architecture**: Same setup works in dev container and production
+- **Lightweight**: Bugsink runs in a single process, unlike full Sentry (16GB+ RAM)
+- **Error correlation**: Request IDs allow correlation between frontend errors and backend logs
+
+### Negative
+
+- **Additional services**: Bugsink and Logstash add complexity to the container
+- **PostgreSQL overhead**: Additional database for error tracking
+- **Initial setup**: Requires configuration of multiple components
+- **Logstash learning curve**: Pipeline configuration requires Logstash knowledge
+
+## Alternatives Considered
+
+1. **Full Sentry self-hosted**: Rejected due to complexity (Kafka, Redis, ClickHouse, 16GB+ RAM minimum)
+2. **GlitchTip**: Considered, but Bugsink is lighter weight and easier to deploy
+3. **Sentry SaaS**: Rejected due to self-hosted requirement
+4. **Custom error aggregation**: Rejected in favor of proven Sentry SDK ecosystem
+
+## References
+
+- [Bugsink Documentation](https://www.bugsink.com/docs/)
+- [Bugsink Docker Install](https://www.bugsink.com/docs/docker-install/)
+- [@sentry/node Documentation](https://docs.sentry.io/platforms/javascript/guides/node/)
+- [@sentry/react Documentation](https://docs.sentry.io/platforms/javascript/guides/react/)
+- [bugsink-mcp](https://github.com/j-shelfwood/bugsink-mcp)
+- [Logstash Reference](https://www.elastic.co/guide/en/logstash/current/index.html)
+- [ADR-050: PostgreSQL Function Observability](./0050-postgresql-function-observability.md)
+- [ADR-056: Application Performance Monitoring](./0056-application-performance-monitoring.md)

docs/adr/0048-authentication-strategy.md

@@ -2,22 +2,22 @@
 
 **Date**: 2026-01-09
 
-**Status**: Partially Implemented
+**Status**: Accepted (Fully Implemented)
 
-**Implemented**: 2026-01-09 (Local auth only)
+**Implemented**: 2026-01-09 (Local auth + JWT), 2026-01-26 (OAuth enabled)
 
 ## Context
 
 The application requires a secure authentication system that supports both traditional email/password login and social OAuth providers (Google, GitHub). The system must handle user sessions, token refresh, account security (lockout after failed attempts), and integrate seamlessly with the existing Express middleware pipeline.
 
-Currently, **only local authentication is enabled**. OAuth strategies are fully implemented but commented out, pending configuration of OAuth provider credentials.
+**All authentication methods are now fully implemented**: Local authentication (email/password), JWT tokens, and OAuth (Google + GitHub). OAuth strategies use conditional registration - they activate automatically when the corresponding environment variables are configured.
 
 ## Decision
 
 We will implement a stateless JWT-based authentication system with the following components:
 
 1. **Local Authentication**: Email/password login with bcrypt hashing.
-2. **OAuth Authentication**: Google and GitHub OAuth 2.0 (currently disabled).
+2. **OAuth Authentication**: Google and GitHub OAuth 2.0 (conditionally enabled via environment variables).
 3. **JWT Access Tokens**: Short-lived tokens (15 minutes) for API authentication.
 4. **Refresh Tokens**: Long-lived tokens (7 days) stored in HTTP-only cookies.
 5. **Account Security**: Lockout after 5 failed login attempts for 15 minutes.
@@ -59,7 +59,7 @@ We will implement a stateless JWT-based authentication system with the following
 │       │                                  │              │           │
 │       │         ┌──────────┐             │              │           │
 │       └────────>│  OAuth   │─────────────┘              │           │
-│    (disabled)   │ Provider │                            │           │
+│                 │ Provider │                            │           │
 │                 └──────────┘                            │           │
 │                                                         │           │
 │  ┌──────────┐    ┌──────────┐                          │           │
@@ -130,72 +130,139 @@ passport.use(
 - Refresh token: 7 days expiry, 64-byte random hex
 - Refresh token stored in HTTP-only cookie with `secure` flag in production
 
-### OAuth Strategies (Disabled)
+### OAuth Strategies (Conditionally Enabled)
+
+OAuth strategies are **fully implemented** and activate automatically when the corresponding environment variables are set. The strategies use conditional registration to gracefully handle missing credentials.
 
 #### Google OAuth
 
-Located in `src/routes/passport.routes.ts` (lines 167-217, commented):
+Located in `src/config/passport.ts` (lines 167-235):
 
 ```typescript
-// passport.use(new GoogleStrategy({
-//     clientID: process.env.GOOGLE_CLIENT_ID!,
-//     clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
-//     callbackURL: '/api/auth/google/callback',
-//     scope: ['profile', 'email']
-//   },
-//   async (accessToken, refreshToken, profile, done) => {
-//     const email = profile.emails?.[0]?.value;
-//     const user = await db.findUserByEmail(email);
-//     if (user) {
-//       return done(null, user);
-//     }
-//     // Create new user with null password_hash
-//     const newUser = await db.createUser(email, null, {
-//       full_name: profile.displayName,
-//       avatar_url: profile.photos?.[0]?.value
-//     });
-//     return done(null, newUser);
-//   }
-// ));
+// Only register the strategy if the required environment variables are set.
+if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+  passport.use(
+    new GoogleStrategy(
+      {
+        clientID: process.env.GOOGLE_CLIENT_ID,
+        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+        callbackURL: '/api/auth/google/callback',
+        scope: ['profile', 'email'],
+      },
+      async (_accessToken, _refreshToken, profile, done) => {
+        const email = profile.emails?.[0]?.value;
+        if (!email) {
+          return done(new Error('No email found in Google profile.'), false);
+        }
+
+        const existingUserProfile = await db.userRepo.findUserWithProfileByEmail(email, logger);
+        if (existingUserProfile) {
+          // User exists, log them in (strip sensitive fields)
+          return done(null, cleanUserProfile);
+        } else {
+          // Create new user with null password_hash for OAuth users
+          const newUserProfile = await db.userRepo.createUser(
+            email,
+            null,
+            {
+              full_name: profile.displayName,
+              avatar_url: profile.photos?.[0]?.value,
+            },
+            logger,
+          );
+          return done(null, newUserProfile);
+        }
+      },
+    ),
+  );
+  logger.info('[Passport] Google OAuth strategy registered.');
+} else {
+  logger.warn('[Passport] Google OAuth strategy NOT registered: credentials not set.');
+}
 ```
 
 #### GitHub OAuth
 
-Located in `src/routes/passport.routes.ts` (lines 219-269, commented):
+Located in `src/config/passport.ts` (lines 237-310):
 
 ```typescript
-// passport.use(new GitHubStrategy({
-//     clientID: process.env.GITHUB_CLIENT_ID!,
-//     clientSecret: process.env.GITHUB_CLIENT_SECRET!,
-//     callbackURL: '/api/auth/github/callback',
-//     scope: ['user:email']
-//   },
-//   async (accessToken, refreshToken, profile, done) => {
-//     const email = profile.emails?.[0]?.value;
-//     // Similar flow to Google OAuth
-//   }
-// ));
+// Only register the strategy if the required environment variables are set.
+if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
+  passport.use(
+    new GitHubStrategy(
+      {
+        clientID: process.env.GITHUB_CLIENT_ID,
+        clientSecret: process.env.GITHUB_CLIENT_SECRET,
+        callbackURL: '/api/auth/github/callback',
+        scope: ['user:email'],
+      },
+      async (_accessToken, _refreshToken, profile, done) => {
+        const email = profile.emails?.[0]?.value;
+        if (!email) {
+          return done(new Error('No public email found in GitHub profile.'), false);
+        }
+        // Same flow as Google OAuth - find or create user
+      },
+    ),
+  );
+  logger.info('[Passport] GitHub OAuth strategy registered.');
+} else {
+  logger.warn('[Passport] GitHub OAuth strategy NOT registered: credentials not set.');
+}
 ```
 
-#### OAuth Routes (Disabled)
+#### OAuth Routes (Active)
 
-Located in `src/routes/auth.routes.ts` (lines 289-315, commented):
+Located in `src/routes/auth.routes.ts` (lines 587-609):
 
 ```typescript
-// const handleOAuthCallback = (req, res) => {
-//     const user = req.user;
-//     const accessToken = jwt.sign(payload, JWT_SECRET, { expiresIn: '15m' });
-//     const refreshToken = crypto.randomBytes(64).toString('hex');
-//
-//     await db.saveRefreshToken(user.user_id, refreshToken);
-//     res.cookie('refreshToken', refreshToken, { httpOnly: true, secure: true });
-//     res.redirect(`${FRONTEND_URL}/auth/callback?token=${accessToken}`);
-// };
+// Google OAuth routes
+router.get('/google', passport.authenticate('google', { session: false }));
+router.get(
+  '/google/callback',
+  passport.authenticate('google', {
+    session: false,
+    failureRedirect: '/?error=google_auth_failed',
+  }),
+  createOAuthCallbackHandler('google'),
+);
 
-// router.get('/google', passport.authenticate('google', { session: false }));
-// router.get('/google/callback', passport.authenticate('google', { ... }), handleOAuthCallback);
-// router.get('/github', passport.authenticate('github', { session: false }));
-// router.get('/github/callback', passport.authenticate('github', { ... }), handleOAuthCallback);
+// GitHub OAuth routes
+router.get('/github', passport.authenticate('github', { session: false }));
+router.get(
+  '/github/callback',
+  passport.authenticate('github', {
+    session: false,
+    failureRedirect: '/?error=github_auth_failed',
+  }),
+  createOAuthCallbackHandler('github'),
+);
+```
+
+#### OAuth Callback Handler
+
+The callback handler generates tokens and redirects to the frontend:
+
+```typescript
+const createOAuthCallbackHandler = (provider: 'google' | 'github') => {
+  return async (req: Request, res: Response) => {
+    const userProfile = req.user as UserProfile;
+    const { accessToken, refreshToken } = await authService.handleSuccessfulLogin(
+      userProfile,
+      req.log,
+    );
+
+    res.cookie('refreshToken', refreshToken, {
+      httpOnly: true,
+      secure: process.env.NODE_ENV === 'production',
+      maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
+    });
+
+    // Redirect to frontend with provider-specific token param
+    const tokenParam = provider === 'google' ? 'googleAuthToken' : 'githubAuthToken';
+    res.redirect(`${process.env.FRONTEND_URL}/?${tokenParam}=${accessToken}`);
+  };
+};
 ```
 
 ### Database Schema
@@ -248,11 +315,13 @@ export const mockAuth = (req, res, next) => {
 };
 ```
 
-## Enabling OAuth
+## Configuring OAuth Providers
+
+OAuth is fully implemented and activates automatically when credentials are provided. No code changes are required.
 
 ### Step 1: Set Environment Variables
 
-Add to `.env`:
+Add to your environment (`.env.local` for development, Gitea secrets for production):
 
 ```bash
 # Google OAuth
@@ -283,54 +352,29 @@ GITHUB_CLIENT_SECRET=your-github-client-secret
    - Development: `http://localhost:3001/api/auth/github/callback`
    - Production: `https://your-domain.com/api/auth/github/callback`
 
-### Step 3: Uncomment Backend Code
+### Step 3: Restart the Application
 
-**In `src/routes/passport.routes.ts`**:
+After setting the environment variables, restart PM2:
 
-1. Uncomment import statements (lines 5-6):
-
-   ```typescript
-   import { Strategy as GoogleStrategy } from 'passport-google-oauth20';
-   import { Strategy as GitHubStrategy } from 'passport-github2';
-   ```
-
-2. Uncomment Google strategy (lines 167-217)
-3. Uncomment GitHub strategy (lines 219-269)
-
-**In `src/routes/auth.routes.ts`**:
-
-1. Uncomment `handleOAuthCallback` function (lines 291-309)
-2. Uncomment OAuth routes (lines 311-315)
-
-### Step 4: Add Frontend OAuth Buttons
-
-Create login buttons that redirect to:
-
-- Google: `GET /api/auth/google`
-- GitHub: `GET /api/auth/github`
-
-Handle callback at `/auth/callback?token=<accessToken>`:
-
-1. Extract token from URL
-2. Store in client-side token storage
-3. Redirect to dashboard
-
-### Step 5: Handle OAuth Callback Page
-
-Create `src/pages/AuthCallback.tsx`:
-
-```typescript
-const AuthCallback = () => {
-  const token = new URLSearchParams(location.search).get('token');
-  if (token) {
-    setToken(token);
-    navigate('/dashboard');
-  } else {
-    navigate('/login?error=auth_failed');
-  }
-};
+```bash
+podman exec -it flyer-crawler-dev pm2 restart all
 ```
 
+The Passport configuration will automatically register the OAuth strategies when it detects the credentials. Check the logs for confirmation:
+
+```text
+[Passport] Google OAuth strategy registered.
+[Passport] GitHub OAuth strategy registered.
+```
+
+### Frontend Integration
+
+OAuth login buttons are implemented in `src/client/pages/AuthView.tsx`. The frontend:
+
+1. Redirects users to `/api/auth/google` or `/api/auth/github`
+2. Handles the callback via the `useAppInitialization` hook which looks for `googleAuthToken` or `githubAuthToken` query parameters
+3. Stores the token and redirects to the dashboard
+
 ## Known Limitations
 
 1. **No OAuth Provider ID Mapping**: Users are identified by email only. If a user has accounts with different emails on Google and GitHub, they create separate accounts.
@@ -372,31 +416,32 @@ const AuthCallback = () => {
 - **Stateless Architecture**: No session storage required; scales horizontally.
 - **Secure by Default**: HTTP-only cookies, short token expiry, bcrypt hashing.
 - **Account Protection**: Lockout prevents brute-force attacks.
-- **Flexible OAuth**: Can enable/disable OAuth without code changes (just env vars + uncommenting).
-- **Graceful Degradation**: System works with local auth only.
+- **Flexible OAuth**: OAuth activates automatically when credentials are set - no code changes needed.
+- **Graceful Degradation**: System works with local auth only when OAuth credentials are not configured.
+- **Full Feature Set**: Both local and OAuth authentication are production-ready.
 
 ### Negative
 
-- **OAuth Disabled by Default**: Requires manual uncommenting to enable.
-- **No Account Linking**: Multiple OAuth providers create separate accounts.
-- **Frontend Work Required**: OAuth login buttons don't exist yet.
-- **Token in URL**: OAuth callback passes token in URL (visible in browser history).
+- **No Account Linking**: Multiple OAuth providers create separate accounts if emails differ.
+- **Token in URL**: OAuth callback passes token in URL query parameter (visible in browser history).
+- **Email-Based Identity**: OAuth users are identified by email only, not provider-specific IDs.
 
 ### Mitigation
 
-- Document OAuth enablement steps clearly (see [../architecture/AUTHENTICATION.md](../architecture/AUTHENTICATION.md)).
+- Document OAuth configuration steps clearly (see [../architecture/AUTHENTICATION.md](../architecture/AUTHENTICATION.md)).
 - Consider adding OAuth provider ID columns for future account linking.
-- Use URL fragment (`#token=`) instead of query parameter for callback.
+- Consider using URL fragment (`#token=`) instead of query parameter for callback in future enhancement.
 
 ## Key Files
 
 | File                                                   | Purpose                                          |
 | ------------------------------------------------------ | ------------------------------------------------ |
-| `src/routes/passport.routes.ts`                        | Passport strategies (local, JWT, OAuth)          |
+| `src/config/passport.ts`                               | Passport strategies (local, JWT, OAuth)          |
 | `src/routes/auth.routes.ts`                            | Auth endpoints (login, register, refresh, OAuth) |
 | `src/services/authService.ts`                          | Auth business logic                              |
 | `src/services/db/user.db.ts`                           | User database operations                         |
 | `src/config/env.ts`                                    | Environment variable validation                  |
+| `src/client/pages/AuthView.tsx`                        | Frontend login/register UI with OAuth buttons    |
 | [AUTHENTICATION.md](../architecture/AUTHENTICATION.md) | OAuth setup guide                                |
 | `.env.example`                                         | Environment variable template                    |
 
@@ -409,11 +454,11 @@ const AuthCallback = () => {
 
 ## Future Enhancements
 
-1. **Enable OAuth**: Uncomment strategies and configure providers.
-2. **Add OAuth Provider Mapping Table**: Store `googleId`, `githubId` for account linking.
-3. **Implement Account Linking**: Allow users to connect multiple OAuth providers.
-4. **Add Password to OAuth Users**: Allow OAuth users to set a password.
-5. **Implement PKCE**: Add PKCE flow for enhanced OAuth security.
-6. **Token in Fragment**: Use URL fragment for OAuth callback token.
-7. **OAuth Token Storage**: Store OAuth refresh tokens for provider API access.
-8. **Magic Link Login**: Add passwordless email login option.
+1. **Add OAuth Provider Mapping Table**: Store `googleId`, `githubId` for account linking.
+2. **Implement Account Linking**: Allow users to connect multiple OAuth providers.
+3. **Add Password to OAuth Users**: Allow OAuth users to set a password for local login.
+4. **Implement PKCE**: Add PKCE flow for enhanced OAuth security.
+5. **Token in Fragment**: Use URL fragment for OAuth callback token instead of query parameter.
+6. **OAuth Token Storage**: Store OAuth refresh tokens for provider API access.
+7. **Magic Link Login**: Add passwordless email login option.
+8. **Additional OAuth Providers**: Support for Apple, Microsoft, or other providers.

docs/adr/0056-application-performance-monitoring.md

@@ -0,0 +1,262 @@
+# ADR-056: Application Performance Monitoring (APM)
+
+**Date**: 2026-01-26
+
+**Status**: Proposed
+
+**Related**: [ADR-015](./0015-error-tracking-and-observability.md) (Error Tracking and Observability)
+
+## Context
+
+Application Performance Monitoring (APM) provides visibility into application behavior through:
+
+- **Distributed Tracing**: Track requests across services, queues, and database calls
+- **Performance Metrics**: Response times, throughput, error rates
+- **Resource Monitoring**: Memory usage, CPU, database connections
+- **Transaction Analysis**: Identify slow endpoints and bottlenecks
+
+While ADR-015 covers error tracking and observability, APM is a distinct concern focused on performance rather than errors. The Sentry SDK supports APM through its tracing features, but this capability is currently **intentionally disabled** in our application.
+
+### Current State
+
+The Sentry SDK is installed and configured for error tracking (see ADR-015), but APM features are disabled:
+
+```typescript
+// src/services/sentry.client.ts
+Sentry.init({
+  dsn: config.sentry.dsn,
+  environment: config.sentry.environment,
+  // Performance monitoring - disabled for now to keep it simple
+  tracesSampleRate: 0,
+  // ...
+});
+```
+
+```typescript
+// src/services/sentry.server.ts
+Sentry.init({
+  dsn: config.sentry.dsn,
+  environment: config.sentry.environment || config.server.nodeEnv,
+  // Performance monitoring - disabled for now to keep it simple
+  tracesSampleRate: 0,
+  // ...
+});
+```
+
+### Why APM is Currently Disabled
+
+1. **Complexity**: APM adds overhead and complexity to debugging
+2. **Bugsink Limitations**: Bugsink's APM support is less mature than its error tracking
+3. **Resource Overhead**: Tracing adds memory and CPU overhead
+4. **Focus**: Error tracking provides more immediate value for our current scale
+5. **Cost**: High sample rates can significantly increase storage requirements
+
+## Decision
+
+We propose a **staged approach** to APM implementation:
+
+### Phase 1: Selective Backend Tracing (Low Priority)
+
+Enable tracing for specific high-value operations:
+
+```typescript
+// Enable tracing for specific transactions only
+Sentry.init({
+  dsn: config.sentry.dsn,
+  tracesSampleRate: 0, // Keep default at 0
+
+  // Trace only specific high-value transactions
+  tracesSampler: (samplingContext) => {
+    const transactionName = samplingContext.transactionContext?.name;
+
+    // Always trace flyer processing jobs
+    if (transactionName?.includes('flyer-processing')) {
+      return 0.1; // 10% sample rate
+    }
+
+    // Always trace AI/Gemini calls
+    if (transactionName?.includes('gemini')) {
+      return 0.5; // 50% sample rate
+    }
+
+    // Trace slow endpoints (determined by custom logic)
+    if (samplingContext.parentSampled) {
+      return 0.1; // 10% for child transactions
+    }
+
+    return 0; // Don't trace other transactions
+  },
+});
+```
+
+### Phase 2: Custom Performance Metrics
+
+Add custom metrics without full tracing overhead:
+
+```typescript
+// Custom metric for slow database queries
+import { metrics } from '@sentry/node';
+
+// In repository methods
+const startTime = performance.now();
+const result = await pool.query(sql, params);
+const duration = performance.now() - startTime;
+
+metrics.distribution('db.query.duration', duration, {
+  tags: { query_type: 'select', table: 'flyers' },
+});
+
+if (duration > 1000) {
+  logger.warn({ duration, sql }, 'Slow query detected');
+}
+```
+
+### Phase 3: Full APM Integration (Future)
+
+When/if full APM is needed:
+
+```typescript
+Sentry.init({
+  dsn: config.sentry.dsn,
+  tracesSampleRate: 0.1, // 10% of transactions
+  profilesSampleRate: 0.1, // 10% of traced transactions get profiled
+
+  integrations: [
+    // Database tracing
+    Sentry.postgresIntegration(),
+    // Redis tracing
+    Sentry.redisIntegration(),
+    // BullMQ job tracing
+    Sentry.prismaIntegration(), // or custom BullMQ integration
+  ],
+});
+```
+
+## Implementation Steps
+
+### To Enable Basic APM
+
+1. **Update Sentry Configuration**:
+   - Set `tracesSampleRate` > 0 in `src/services/sentry.server.ts`
+   - Set `tracesSampleRate` > 0 in `src/services/sentry.client.ts`
+   - Add environment variable `SENTRY_TRACES_SAMPLE_RATE` (default: 0)
+
+2. **Add Instrumentation**:
+   - Enable automatic Express instrumentation
+   - Add manual spans for BullMQ job processing
+   - Add database query instrumentation
+
+3. **Frontend Tracing**:
+   - Add Browser Tracing integration
+   - Configure page load and navigation tracing
+
+4. **Environment Variables**:
+
+   ```bash
+   SENTRY_TRACES_SAMPLE_RATE=0.1  # 10% sampling
+   SENTRY_PROFILES_SAMPLE_RATE=0  # Profiling disabled
+   ```
+
+5. **Bugsink Configuration**:
+   - Verify Bugsink supports performance data ingestion
+   - Configure retention policies for performance data
+
+### Configuration Changes Required
+
+```typescript
+// src/config/env.ts - Add new config
+sentry: {
+  dsn: env.SENTRY_DSN,
+  environment: env.SENTRY_ENVIRONMENT,
+  debug: env.SENTRY_DEBUG === 'true',
+  tracesSampleRate: parseFloat(env.SENTRY_TRACES_SAMPLE_RATE || '0'),
+  profilesSampleRate: parseFloat(env.SENTRY_PROFILES_SAMPLE_RATE || '0'),
+},
+```
+
+```typescript
+// src/services/sentry.server.ts - Updated init
+Sentry.init({
+  dsn: config.sentry.dsn,
+  environment: config.sentry.environment,
+  tracesSampleRate: config.sentry.tracesSampleRate,
+  profilesSampleRate: config.sentry.profilesSampleRate,
+  // ... rest of config
+});
+```
+
+## Trade-offs
+
+### Enabling APM
+
+**Benefits**:
+
+- Identify performance bottlenecks
+- Track distributed transactions across services
+- Profile slow endpoints
+- Monitor resource utilization trends
+
+**Costs**:
+
+- Increased memory usage (~5-15% overhead)
+- Additional CPU for trace processing
+- Increased storage in Bugsink/Sentry
+- More complex debugging (noise in traces)
+- Potential latency from tracing overhead
+
+### Keeping APM Disabled
+
+**Benefits**:
+
+- Simpler operation and debugging
+- Lower resource overhead
+- Focused on error tracking (higher priority)
+- No additional storage costs
+
+**Costs**:
+
+- No automated performance insights
+- Manual profiling required for bottleneck detection
+- Limited visibility into slow transactions
+
+## Alternatives Considered
+
+1. **OpenTelemetry**: More vendor-neutral, but adds another dependency and complexity
+2. **Prometheus + Grafana**: Good for metrics, but doesn't provide distributed tracing
+3. **Jaeger/Zipkin**: Purpose-built for tracing, but requires additional infrastructure
+4. **New Relic/Datadog SaaS**: Full-featured but conflicts with self-hosted requirement
+
+## Current Recommendation
+
+**Keep APM disabled** (`tracesSampleRate: 0`) until:
+
+1. Specific performance issues are identified that require tracing
+2. Bugsink's APM support is verified and tested
+3. Infrastructure can support the additional overhead
+4. There is a clear business need for performance visibility
+
+When enabling APM becomes necessary, start with Phase 1 (selective tracing) to minimize overhead while gaining targeted insights.
+
+## Consequences
+
+### Positive (When Implemented)
+
+- Automated identification of slow endpoints
+- Distributed trace visualization across async operations
+- Correlation between errors and performance issues
+- Proactive alerting on performance degradation
+
+### Negative
+
+- Additional infrastructure complexity
+- Storage overhead for trace data
+- Potential performance impact from tracing itself
+- Learning curve for trace analysis
+
+## References
+
+- [Sentry Performance Monitoring](https://docs.sentry.io/product/performance/)
+- [@sentry/node Performance](https://docs.sentry.io/platforms/javascript/guides/node/performance/)
+- [@sentry/react Performance](https://docs.sentry.io/platforms/javascript/guides/react/performance/)
+- [OpenTelemetry](https://opentelemetry.io/) (alternative approach)
+- [ADR-015: Error Tracking and Observability](./0015-error-tracking-and-observability.md)

docs/adr/adr-implementation-tracker.md

@@ -15,9 +15,9 @@ This document tracks the implementation status and estimated effort for all Arch
 
 | Status                       | Count |
 | ---------------------------- | ----- |
-| Accepted (Fully Implemented) | 36    |
-| Partially Implemented        | 3     |
-| Proposed (Not Started)       | 16    |
+| Accepted (Fully Implemented) | 39    |
+| Partially Implemented        | 2     |
+| Proposed (Not Started)       | 15    |
 
 ---
 
@@ -49,7 +49,7 @@ This document tracks the implementation status and estimated effort for all Arch
 | [ADR-003](./0003-standardized-input-validation-using-middleware.md) | Input Validation         | Accepted    | -      | Fully implemented                     |
 | [ADR-008](./0008-api-versioning-strategy.md)                        | API Versioning           | Proposed    | L      | Major URL/routing changes             |
 | [ADR-018](./0018-api-documentation-strategy.md)                     | API Documentation        | Accepted    | -      | OpenAPI/Swagger implemented           |
-| [ADR-022](./0022-real-time-notification-system.md)                  | Real-time Notifications  | Proposed    | XL     | WebSocket infrastructure              |
+| [ADR-022](./0022-real-time-notification-system.md)                  | Real-time Notifications  | Accepted    | -      | Fully implemented                     |
 | [ADR-028](./0028-api-response-standardization.md)                   | Response Standardization | Implemented | L      | Completed (routes, middleware, tests) |
 
 ### Category 4: Security & Compliance
@@ -62,17 +62,18 @@ This document tracks the implementation status and estimated effort for all Arch
 | [ADR-029](./0029-secret-rotation-and-key-management.md)                 | Secret Rotation       | Proposed | L      | Infrastructure changes needed    |
 | [ADR-032](./0032-rate-limiting-strategy.md)                             | Rate Limiting         | Accepted | -      | Fully implemented                |
 | [ADR-033](./0033-file-upload-and-storage-strategy.md)                   | File Upload & Storage | Accepted | -      | Fully implemented                |
-| [ADR-048](./0048-authentication-strategy.md)                            | Authentication        | Partial  | M      | JWT done, OAuth pending          |
+| [ADR-048](./0048-authentication-strategy.md)                            | Authentication        | Accepted | -      | Fully implemented                |
 
 ### Category 5: Observability & Monitoring
 
-| ADR                                                                        | Title                       | Status   | Effort | Notes                   |
-| -------------------------------------------------------------------------- | --------------------------- | -------- | ------ | ----------------------- |
-| [ADR-004](./0004-standardized-application-wide-structured-logging.md)      | Structured Logging          | Accepted | -      | Fully implemented       |
-| [ADR-015](./0015-application-performance-monitoring-and-error-tracking.md) | APM & Error Tracking        | Proposed | M      | Third-party integration |
-| [ADR-050](./0050-postgresql-function-observability.md)                     | PostgreSQL Fn Observability | Accepted | -      | Fully implemented       |
-| [ADR-051](./0051-asynchronous-context-propagation.md)                      | Context Propagation         | Accepted | -      | Fully implemented       |
-| [ADR-052](./0052-granular-debug-logging-strategy.md)                       | Granular Debug Logging      | Accepted | -      | Fully implemented       |
+| ADR                                                                   | Title                       | Status   | Effort | Notes                                      |
+| --------------------------------------------------------------------- | --------------------------- | -------- | ------ | ------------------------------------------ |
+| [ADR-004](./0004-standardized-application-wide-structured-logging.md) | Structured Logging          | Accepted | -      | Fully implemented                          |
+| [ADR-015](./0015-error-tracking-and-observability.md)                 | Error Tracking              | Accepted | -      | Fully implemented                          |
+| [ADR-050](./0050-postgresql-function-observability.md)                | PostgreSQL Fn Observability | Accepted | -      | Fully implemented                          |
+| [ADR-051](./0051-asynchronous-context-propagation.md)                 | Context Propagation         | Accepted | -      | Fully implemented                          |
+| [ADR-052](./0052-granular-debug-logging-strategy.md)                  | Granular Debug Logging      | Accepted | -      | Fully implemented                          |
+| [ADR-056](./0056-application-performance-monitoring.md)               | APM (Performance)           | Proposed | M      | tracesSampleRate=0, intentionally disabled |
 
 ### Category 6: Deployment & Operations
 
@@ -127,51 +128,55 @@ This document tracks the implementation status and estimated effort for all Arch
 
 ## Work Still To Be Completed (Priority Order)
 
-These ADRs are proposed but not yet implemented, ordered by suggested implementation priority:
+These ADRs are proposed or partially implemented, ordered by suggested implementation priority:
 
-| Priority | ADR     | Title                    | Effort | Rationale                            |
-| -------- | ------- | ------------------------ | ------ | ------------------------------------ |
-| 1        | ADR-015 | APM & Error Tracking     | M      | Production visibility, debugging     |
-| 2        | ADR-024 | Feature Flags            | M      | Safer deployments, A/B testing       |
-| 3        | ADR-054 | Bugsink-Gitea Sync       | L      | Automated issue tracking from errors |
-| 4        | ADR-023 | Schema Migrations v2     | L      | Database evolution support           |
-| 5        | ADR-029 | Secret Rotation          | L      | Security improvement                 |
-| 6        | ADR-008 | API Versioning           | L      | Future API evolution                 |
-| 7        | ADR-030 | Circuit Breaker          | L      | Resilience improvement               |
-| 8        | ADR-022 | Real-time Notifications  | XL     | Major feature enhancement            |
-| 9        | ADR-011 | Authorization & RBAC     | XL     | Advanced permission system           |
-| 10       | ADR-025 | i18n & l10n              | XL     | Multi-language support               |
-| 11       | ADR-031 | Data Retention & Privacy | XL     | Compliance requirements              |
+| Priority | ADR     | Title                    | Status   | Effort | Rationale                            |
+| -------- | ------- | ------------------------ | -------- | ------ | ------------------------------------ |
+| 1        | ADR-024 | Feature Flags            | Proposed | M      | Safer deployments, A/B testing       |
+| 2        | ADR-054 | Bugsink-Gitea Sync       | Proposed | L      | Automated issue tracking from errors |
+| 3        | ADR-023 | Schema Migrations v2     | Proposed | L      | Database evolution support           |
+| 4        | ADR-029 | Secret Rotation          | Proposed | L      | Security improvement                 |
+| 5        | ADR-008 | API Versioning           | Proposed | L      | Future API evolution                 |
+| 6        | ADR-030 | Circuit Breaker          | Proposed | L      | Resilience improvement               |
+| 7        | ADR-056 | APM (Performance)        | Proposed | M      | Enable when performance issues arise |
+| 8        | ADR-011 | Authorization & RBAC     | Proposed | XL     | Advanced permission system           |
+| 9        | ADR-025 | i18n & l10n              | Proposed | XL     | Multi-language support               |
+| 10       | ADR-031 | Data Retention & Privacy | Proposed | XL     | Compliance requirements              |
 
 ---
 
 ## Recent Implementation History
 
-| Date       | ADR     | Change                                                                               |
-| ---------- | ------- | ------------------------------------------------------------------------------------ |
-| 2026-01-26 | ADR-052 | Marked as fully implemented - createScopedLogger with DEBUG_MODULES support complete |
-| 2026-01-26 | ADR-053 | Marked as fully implemented - /health/queues endpoint and worker heartbeats complete |
-| 2026-01-26 | ADR-050 | Marked as fully implemented - PostgreSQL function observability complete             |
-| 2026-01-26 | ADR-055 | Created (renumbered from duplicate ADR-023) - Database normalization                 |
-| 2026-01-26 | ADR-054 | Added to tracker - Bugsink to Gitea issue synchronization                            |
-| 2026-01-26 | ADR-053 | Added to tracker - Worker health checks and monitoring                               |
-| 2026-01-26 | ADR-052 | Added to tracker - Granular debug logging strategy                                   |
-| 2026-01-26 | ADR-051 | Added to tracker - Asynchronous context propagation                                  |
-| 2026-01-26 | ADR-048 | Added to tracker - Authentication strategy                                           |
-| 2026-01-26 | ADR-040 | Added to tracker - Testing economics and priorities                                  |
-| 2026-01-17 | ADR-054 | Created - Bugsink-Gitea sync worker proposal                                         |
-| 2026-01-11 | ADR-050 | Created - PostgreSQL function observability with fn_log() and Logstash               |
-| 2026-01-11 | ADR-018 | Implemented - OpenAPI/Swagger documentation at /docs/api-docs                        |
-| 2026-01-11 | ADR-049 | Created - Gamification system, achievements, and testing requirements                |
-| 2026-01-09 | ADR-047 | Created - Project file/folder organization with migration plan                       |
-| 2026-01-09 | ADR-041 | Created - AI/Gemini integration with model fallback and rate limiting                |
-| 2026-01-09 | ADR-042 | Created - Email and notification architecture with BullMQ queuing                    |
-| 2026-01-09 | ADR-043 | Created - Express middleware pipeline ordering and patterns                          |
-| 2026-01-09 | ADR-044 | Created - Frontend feature-based folder organization                                 |
-| 2026-01-09 | ADR-045 | Created - Test data factory pattern for mock generation                              |
-| 2026-01-09 | ADR-046 | Created - Image processing pipeline with Sharp and EXIF stripping                    |
-| 2026-01-09 | ADR-026 | Fully implemented - client-side structured logger                                    |
-| 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated                        |
+| Date       | ADR     | Change                                                                       |
+| ---------- | ------- | ---------------------------------------------------------------------------- |
+| 2026-01-26 | ADR-015 | Completed - Added Sentry user context in AuthProvider, now fully implemented |
+| 2026-01-26 | ADR-056 | Created - APM split from ADR-015, status Proposed (tracesSampleRate=0)       |
+| 2026-01-26 | ADR-015 | Refactored to focus on error tracking only, temporarily status Partial       |
+| 2026-01-26 | ADR-048 | Verified as fully implemented - JWT + OAuth authentication complete          |
+| 2026-01-26 | ADR-022 | Verified as fully implemented - WebSocket notifications complete             |
+| 2026-01-26 | ADR-052 | Marked as fully implemented - createScopedLogger complete                    |
+| 2026-01-26 | ADR-053 | Marked as fully implemented - /health/queues endpoint complete               |
+| 2026-01-26 | ADR-050 | Marked as fully implemented - PostgreSQL function observability              |
+| 2026-01-26 | ADR-055 | Created (renumbered from duplicate ADR-023) - DB normalization               |
+| 2026-01-26 | ADR-054 | Added to tracker - Bugsink to Gitea issue synchronization                    |
+| 2026-01-26 | ADR-053 | Added to tracker - Worker health checks and monitoring                       |
+| 2026-01-26 | ADR-052 | Added to tracker - Granular debug logging strategy                           |
+| 2026-01-26 | ADR-051 | Added to tracker - Asynchronous context propagation                          |
+| 2026-01-26 | ADR-048 | Added to tracker - Authentication strategy                                   |
+| 2026-01-26 | ADR-040 | Added to tracker - Testing economics and priorities                          |
+| 2026-01-17 | ADR-054 | Created - Bugsink-Gitea sync worker proposal                                 |
+| 2026-01-11 | ADR-050 | Created - PostgreSQL function observability with fn_log()                    |
+| 2026-01-11 | ADR-018 | Implemented - OpenAPI/Swagger documentation at /docs/api-docs                |
+| 2026-01-11 | ADR-049 | Created - Gamification system, achievements, and testing                     |
+| 2026-01-09 | ADR-047 | Created - Project file/folder organization with migration plan               |
+| 2026-01-09 | ADR-041 | Created - AI/Gemini integration with model fallback                          |
+| 2026-01-09 | ADR-042 | Created - Email and notification architecture with BullMQ                    |
+| 2026-01-09 | ADR-043 | Created - Express middleware pipeline ordering and patterns                  |
+| 2026-01-09 | ADR-044 | Created - Frontend feature-based folder organization                         |
+| 2026-01-09 | ADR-045 | Created - Test data factory pattern for mock generation                      |
+| 2026-01-09 | ADR-046 | Created - Image processing pipeline with Sharp and EXIF stripping            |
+| 2026-01-09 | ADR-026 | Fully implemented - client-side structured logger                            |
+| 2026-01-09 | ADR-028 | Fully implemented - all routes, middleware, and tests updated                |
 
 ---
 

docs/adr/index.md

@@ -38,10 +38,11 @@ This directory contains a log of the architectural decisions made for the Flyer
 ## 5. Observability & Monitoring
 
 **[ADR-004](./0004-standardized-application-wide-structured-logging.md)**: Standardized Application-Wide Structured Logging (Accepted)
-**[ADR-015](./0015-application-performance-monitoring-and-error-tracking.md)**: Application Performance Monitoring (APM) and Error Tracking (Proposed)
-**[ADR-050](./0050-postgresql-function-observability.md)**: PostgreSQL Function Observability (Proposed)
+**[ADR-015](./0015-error-tracking-and-observability.md)**: Error Tracking and Observability (Partial)
+**[ADR-050](./0050-postgresql-function-observability.md)**: PostgreSQL Function Observability (Accepted)
 **[ADR-051](./0051-asynchronous-context-propagation.md)**: Asynchronous Context Propagation (Accepted)
-**[ADR-052](./0052-granular-debug-logging-strategy.md)**: Granular Debug Logging Strategy (Proposed)
+**[ADR-052](./0052-granular-debug-logging-strategy.md)**: Granular Debug Logging Strategy (Accepted)
+**[ADR-056](./0056-application-performance-monitoring.md)**: Application Performance Monitoring (Proposed)
 
 ## 6. Deployment & Operations
 

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "flyer-crawler",
-  "version": "0.12.14",
+  "version": "0.12.15",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "flyer-crawler",
-      "version": "0.12.14",
+      "version": "0.12.15",
       "dependencies": {
         "@bull-board/api": "^6.14.2",
         "@bull-board/express": "^6.14.2",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "flyer-crawler",
   "private": true,
-  "version": "0.12.14",
+  "version": "0.12.15",
   "type": "module",
   "scripts": {
     "dev": "concurrently \"npm:start:dev\" \"vite\"",

src/config/env.ts

@@ -112,6 +112,15 @@ const googleSchema = z.object({
   clientSecret: z.string().optional(),
 });
 
+/**
+ * GitHub OAuth configuration schema.
+ * Used for GitHub social login functionality.
+ */
+const githubSchema = z.object({
+  clientId: z.string().optional(),
+  clientSecret: z.string().optional(),
+});
+
 /**
  * Worker concurrency configuration schema.
  */
@@ -157,6 +166,7 @@ const envSchema = z.object({
   ai: aiSchema,
   upc: upcSchema,
   google: googleSchema,
+  github: githubSchema,
   worker: workerSchema,
   server: serverSchema,
   sentry: sentrySchema,
@@ -209,6 +219,10 @@ function loadEnvVars(): unknown {
       clientId: process.env.GOOGLE_CLIENT_ID,
       clientSecret: process.env.GOOGLE_CLIENT_SECRET,
     },
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    },
     worker: {
       concurrency: process.env.WORKER_CONCURRENCY,
       lockDuration: process.env.WORKER_LOCK_DURATION,
@@ -367,3 +381,13 @@ export const isUpcItemDbConfigured = !!config.upc.upcItemDbApiKey;
  * Returns true if Barcode Lookup API is configured.
  */
 export const isBarcodeLookupConfigured = !!config.upc.barcodeLookupApiKey;
+
+/**
+ * Returns true if Google OAuth is configured (both client ID and secret present).
+ */
+export const isGoogleOAuthConfigured = !!config.google.clientId && !!config.google.clientSecret;
+
+/**
+ * Returns true if GitHub OAuth is configured (both client ID and secret present).
+ */
+export const isGithubOAuthConfigured = !!config.github.clientId && !!config.github.clientSecret;

src/providers/AuthProvider.tsx

@@ -7,6 +7,7 @@ import * as apiClient from '../services/apiClient';
 import { useAuthProfileQuery, AUTH_PROFILE_QUERY_KEY } from '../hooks/queries/useAuthProfileQuery';
 import { getToken, setToken, removeToken } from '../services/tokenStorage';
 import { logger } from '../services/logger.client';
+import { setUser as setSentryUser } from '../services/sentry.client';
 
 /**
  * AuthProvider component that manages authentication state.
@@ -40,6 +41,12 @@ export const AuthProvider: React.FC<{ children: ReactNode }> = ({ children }) =>
       logger.info('[AuthProvider] Profile received from query, setting state to AUTHENTICATED.');
       setUserProfile(fetchedProfile);
       setAuthStatus('AUTHENTICATED');
+      // Set Sentry user context for error tracking (ADR-015)
+      setSentryUser({
+        id: fetchedProfile.user.user_id,
+        email: fetchedProfile.user.email,
+        username: fetchedProfile.full_name || fetchedProfile.user.email,
+      });
     } else if (token && isError) {
       logger.warn('[AuthProvider] Token was present but validation failed. Signing out.');
       removeToken();
@@ -66,6 +73,8 @@ export const AuthProvider: React.FC<{ children: ReactNode }> = ({ children }) =>
     setAuthStatus('SIGNED_OUT');
     // Clear the auth profile cache on logout
     queryClient.removeQueries({ queryKey: AUTH_PROFILE_QUERY_KEY });
+    // Clear Sentry user context (ADR-015)
+    setSentryUser(null);
   }, [queryClient]);
 
   const login = useCallback(
@@ -82,6 +91,12 @@ export const AuthProvider: React.FC<{ children: ReactNode }> = ({ children }) =>
         setAuthStatus('AUTHENTICATED');
         // Update the query cache with the provided profile
         queryClient.setQueryData(AUTH_PROFILE_QUERY_KEY, profileData);
+        // Set Sentry user context for error tracking (ADR-015)
+        setSentryUser({
+          id: profileData.user.user_id,
+          email: profileData.user.email,
+          username: profileData.full_name || profileData.user.email,
+        });
         logger.info('[AuthProvider-Login] Login successful. State set to AUTHENTICATED.', {
           user: profileData.user,
         });
@@ -106,6 +121,12 @@ export const AuthProvider: React.FC<{ children: ReactNode }> = ({ children }) =>
           setAuthStatus('AUTHENTICATED');
           // Update the query cache with the fetched profile
           queryClient.setQueryData(AUTH_PROFILE_QUERY_KEY, fetchedProfileData);
+          // Set Sentry user context for error tracking (ADR-015)
+          setSentryUser({
+            id: fetchedProfileData.user.user_id,
+            email: fetchedProfileData.user.email,
+            username: fetchedProfileData.full_name || fetchedProfileData.user.email,
+          });
           logger.info('[AuthProvider-Login] Profile fetch successful. State set to AUTHENTICATED.');
         } catch (e) {
           const errorMessage = e instanceof Error ? e.message : String(e);