# OTel BI Forecast App

OpenTelemetry-instrumented BI platform with microservices, frontend OIDC login plus backend token validation, read-only MSSQL data warehouse access, and PostgreSQL persistence for writable app data.

## Architecture

- Frontend: React + TypeScript (`frontend/`)
- Backend microservices (`backend/microservices/`):
  - `api_gateway`: public API, frontend JWT validation, internal token minting, routing/audit forwarding
  - `bi_query`: read-only MSSQL warehouse queries
  - `analytics`: forecasting, rankings, recommendations
  - `persistence`: PostgreSQL writes/reads for app data
- Data sources:
  - MSSQL (`WorldWideImporters`, `AdventureWorks2022DWH`) read-only only
  - PostgreSQL writable app store (`audit_logs`, `forecast_runs`, `ranking_runs`, `recommendation_runs`)
- Observability: OTLP/HTTP to Grafana Alloy (`/v1/traces`, `/v1/metrics`)

## Authentication Model

- Frontend uses OIDC Authorization Code + PKCE.
- `api_gateway` validates frontend bearer JWT (`iss`, `aud`, signature, expiry, optional scopes) against configured JWKS.
- `api_gateway` mints short-lived internal service tokens (`x-internal-service-token`) for service-to-service calls.
- Internal services (`analytics`, `bi_query`, `persistence`) require valid internal token on non-health endpoints and enforce issuer/type checks.
- Combine with K8s network controls (ClusterIP, NetworkPolicy, mTLS/service mesh where available).

Frontend uses OIDC Authorization Code + PKCE with:
- `VITE_OIDC_ENABLED=true`
- `VITE_OIDC_AUTHORITY=<issuer-base-url>`
- `VITE_OIDC_CLIENT_ID=<frontend-client-id>`
- `VITE_OIDC_REDIRECT_URI=<frontend-url>`
- `VITE_OIDC_POST_LOGOUT_REDIRECT_URI=<frontend-url>`
- `VITE_OIDC_SCOPE=openid profile email`

Backend security env:
- `REQUIRE_FRONTEND_AUTH=true`
- `FRONTEND_JWT_ISSUER_URL=<oidc-issuer>`
- `FRONTEND_JWT_JWKS_URL=<issuer-jwks-url>`
- `FRONTEND_JWT_AUDIENCE=<api-audience>`
- `FRONTEND_REQUIRED_SCOPES=<space-separated>`
- `INTERNAL_SERVICE_SHARED_SECRET=<strong-random-secret-at-least-32-bytes>`
- `INTERNAL_SERVICE_ALLOWED_ISSUERS=api-gateway`
- `MSSQL_TRUST_SERVER_CERTIFICATE=false` and `POSTGRES_SSLMODE=require` for production TLS validation

## Local Run (Microservices)

```bash
cd backend
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
```

Run services in separate terminals:

```bash
uvicorn microservices.persistence.main:app --host 0.0.0.0 --port 8103 --reload
uvicorn microservices.bi_query.main:app --host 0.0.0.0 --port 8101 --reload
uvicorn microservices.analytics.main:app --host 0.0.0.0 --port 8102 --reload
uvicorn microservices.api_gateway.main:app --host 0.0.0.0 --port 8000 --reload
```

Frontend:

```bash
cd frontend
npm install
cp .env.example .env
npm run dev
```

Set:
- `VITE_API_BASE_URL=http://localhost:8000`
- `VITE_OTEL_COLLECTOR_ENDPOINT=http://alloy.monitoring.svc.cluster.local:4318`

Frontend sends `Authorization: Bearer <token>` from the active OIDC session.

## API Endpoints (via Gateway)

- `GET /api/health`
- `GET /api/telemetry/status`
- `GET /api/kpis`
- `GET /api/history?days_back=365`
- `GET /api/forecasts?days=30`
- `GET /api/rankings?top_n=10`
- `GET /api/recommendations`
- `GET /api/dashboard`
- `GET /api/storage/audit-logs?limit=50`
- `GET /api/storage/forecasts?limit=50`
- `GET /api/storage/rankings?limit=50`
- `GET /api/storage/recommendations?limit=50`

## K8s Deployment

Example manifest:
- `k8s/microservices.yaml`

It includes:
- namespace, config map, secret
- deployments/services for `api-gateway`, `bi-query`, `analytics`, `persistence`
- Alloy endpoint wiring via `OTEL_COLLECTOR_ENDPOINT`
- frontend JWT validation config and internal token secret wiring
- hardened pod security defaults (`runAsNonRoot`, dropped capabilities, `seccompProfile: RuntimeDefault`, no auto-mounted service account token)

## Read-Only Guarantee

- MSSQL connections enforce `ApplicationIntent=ReadOnly`.
- Warehouse query layer only accepts `SELECT`/`WITH`.
- Writable operations are isolated to PostgreSQL only.
- Use SQL Server account with `SELECT` grants only.

## OTel Coverage

- Frontend:
  - W3C trace/baggage propagation
  - document-load, user-interaction, fetch, XHR instrumentation
  - manual dashboard spans
- Backend services:
  - FastAPI request spans
  - HTTP client spans for service-to-service calls
  - SQLAlchemy spans (MSSQL and PostgreSQL)
  - manual analytics + persistence spans
  - audit/snapshot persistence telemetry

## Verification

1. Call `GET /api/telemetry/status` with a valid frontend bearer token.
2. Confirm response has non-null `trace_id` and `span_id`.
3. Trigger `GET /api/dashboard`; then verify records in `GET /api/storage/audit-logs`.
4. In Grafana/Tempo, confirm trace path includes:
   - `api-gateway` span
   - `analytics` span
   - `bi-query` MSSQL spans
   - `persistence` PostgreSQL spans
5. Call internal service endpoint directly without `x-internal-service-token` and verify it returns `401`.

## Optional Tests

```bash
cd backend
source .venv/bin/activate
pip install -e .[dev]
pytest
```