shoc-frontend-new/docs/adr/0002-sentry-observability.md

# 0002. Browser error and transaction telemetry with Sentry

## Status

Accepted

## Context

The SeaHaven admin SPA has no centralized browser error reporting or distributed
transaction tracing. Operational failures therefore have to be reconstructed
from user reports and isolated backend logs. We need browser navigation and API
request transactions to join the backend trace while preserving the existing UI,
routing, authentication, and server-state behavior.

## Decision

Use the pinned `@sentry/react` 10.73.0 SDK. Initialize it before the application
router is created, and wrap `createBrowserRouter` with Sentry's current React
Router compatibility API. Configure the browser tracing integration with a 100%
transaction sample rate, and propagate trace headers only to the SPA origin and
the configured `VITE_API_URL` base.

The DSN comes from `VITE_SENTRY_DSN`. It is intentionally treated as public
browser configuration because every `VITE_` value is embedded in the built
JavaScript. `.env.production` commits the public DSN of the real
`shoc-frontend` Sentry project, so dev and staging deploys are live; a missing
or blank DSN in any other build leaves telemetry inactive without preventing
the application from starting. Default personally identifiable information
collection remains disabled.

The Sentry environment label comes from `VITE_SENTRY_ENVIRONMENT` when set and
non-blank, falling back to the Vite build mode otherwise. The committed
`.env.production` labels dev deploys `development`, the staging deploy job
overrides the label to `staging`, and a future production pipeline can set
`production` without code changes.

Source-map upload is outside this change. The Sentry organization and the
`shoc-frontend` project now exist and receive telemetry through the committed
public DSN, but upload still requires a scoped upload token that is not
currently available, plus an explicit deployment design for handling that
credential without exposing it in the browser bundle.

### Alternatives considered

- **Manual error and timing calls** — rejected because they would miss route
  transitions and distributed request context, and would require every feature
  to maintain its own instrumentation.
- **Propagate tracing headers to every request** — rejected because third-party
  requests must not receive SeaHaven trace metadata and broad propagation can
  introduce cross-origin request failures.
- **Add the Sentry Vite plugin now** — rejected until the organization, project,
  upload credential, and deployment ownership are defined.

## Consequences

- Browser navigations and API requests are recorded as connected transactions
  when the deployment supplies a valid DSN.
- Events are labeled by `VITE_SENTRY_ENVIRONMENT` (`development` on dev
  deploys, `staging` on the staging job), falling back to the Vite build mode
  when unset.
- Every transaction is sampled. This meets the current requirement but increases
  event volume and should be reviewed against Sentry quota and retention after
  real traffic is measured.
- Cross-origin API tracing depends on the backend accepting `sentry-trace` and
  `baggage` request headers; the current API CORS policy allows request headers.
- Production stack traces remain minified until source-map upload is designed.
- Rollback is isolated: remove `@sentry/react`, the initialization module and
  import, restore the unwrapped router factory, and remove the Sentry env entries.