slp-modular-cms/aidlc-docs/features/gitea-deployment-workflow/construction/u4-observability/functional-design/domain-entities.md

Domain Entities — U4 Observability Integration

No persisted entity. U4 adds no table, no migration and no database column. It adds two configuration sections, one anonymous endpoint, and build-time frontend values.

---

Concept Relationships

graph TD
    obsconfig["Observability configuration<br/>backend"]
    dsn["Sentry DSN"]
    env["Environment name"]
    release["Release identifier"]
    logging["Structured logger"]
    corr["Correlation identifier"]
    scrubber["Credential scrubber"]
    sentrybe["Sentry client<br/>backend"]
    tunnel["Tunnel endpoint"]
    vite["Vite build-time values<br/>frontend"]
    sentryfe["Sentry client<br/>frontend"]
    umami["Umami script component"]
    apicfg["API base URL resolution"]

    obsconfig --> dsn
    obsconfig --> env
    obsconfig --> release
    dsn --> sentrybe
    dsn --> tunnel
    env --> sentrybe
    release --> sentrybe
    logging --> corr
    logging --> sentrybe
    scrubber -->|"filters before send"| sentrybe
    vite --> sentryfe
    vite --> umami
    vite --> apicfg
    sentryfe -->|"posts envelopes to"| tunnel
    tunnel -->|"forwards to DSN host only"| sentrybe

    classDef cfg fill:#fbd38d,stroke:#c05621,stroke-width:1px,color:#000;
    classDef backend fill:#90cdf4,stroke:#2b6cb0,stroke-width:1px,color:#000;
    classDef frontend fill:#d6bcfa,stroke:#6b46c1,stroke-width:1px,color:#000;
    classDef guard fill:#9ae6b4,stroke:#2f855a,stroke-width:1px,color:#000;
    class obsconfig,dsn,env,release,vite cfg;
    class logging,corr,sentrybe,tunnel backend;
    class sentryfe,umami,apicfg frontend;
    class scrubber guard;

Text alternative: backend configuration supplies the Sentry DSN, environment and release; the structured logger attaches a correlation identifier and feeds Sentry through a credential scrubber; the frontend reads build-time values and routes its error envelopes through the same-origin tunnel, which forwards only to the configured DSN host.

---

Backend configuration — Observability section

Field	Type	Default	Purpose
SentryDsn	string	empty	Absent means Sentry is skipped entirely (BR-U4-08)
Environment	string	falls back to ASPNETCORE_ENVIRONMENT	Tag distinguishing test from production
TunnelMaxPayloadBytes	int	fixed default	Upper bound enforced by the tunnel (BR-U4-17)
TracesSampleRate	double	conservative default	Performance sampling; kept low so the free plan is not exhausted

Not configurable, deliberately: the scrub list (BR-U4-13) and the tunnel's destination host (BR-U4-16). Both are security-critical, and making either configurable would create a way to switch the protection off — the scrub list by omission, the destination by turning the endpoint into a request-forgery primitive.

Secret handling: a Sentry DSN is not a secret in the usual sense — it identifies a project and permits event submission, and the frontend's copy is visible in the page source. It still comes from environment variables in production, consistent with D-16, rather than being committed.

---

Correlation identifier

Aspect	Detail
Purpose	Ties every log entry and Sentry event from one request together (SECURITY-03)
Scope	One request
Presence	On every log entry, not only on errors
Mechanism	Not fixed here — HttpContext.TraceIdentifier versus W3C traceparent is OPEN-01, decided in this unit's NFR Design

Recorded as an entity because the choice affects the shape of every log entry, and NFR Design will settle it rather than leaving it to code generation.

---

Credential scrubber

Not persisted; a filter applied to every outbound Sentry event.

Removed	Reason
Cookie header, entire	Carries the refreshToken. Removing one cookie by rewriting the header is error-prone
Authorization header	Bearer token
X-Master-Api-Key header	Master/slave shared secret
Request body	Login and password-change bodies carry passwords

Retained	Reason
Method, path, query string	Diagnostic value. Note the invitation-token caveat below
User agent	Browser-specific failures
IP address	Attack-pattern recognition
Authenticated username	Whose session hit the problem
Correlation identifier	Ties the event to its log entries

Invitation-token caveat: /api/v1/Invitation/validate?token=… puts a token in the query string, which is retained. It is single-use and time-limited rather than a standing credential, and the value of knowing which endpoint was called outweighs it. Documented so the trade-off is visible.

---

Security event types

Six event shapes, not persisted — emitted as structured log entries that also become Sentry events.

Event	Level	Context
Failed login	Warning	Endpoint, whether the account exists, correlation ID
Authorization denied	Warning	Endpoint, required policy, role held, correlation ID
Master API key rejected	Warning	Endpoint, calling host, correlation ID
Admin bypass rejected	Warning	Path, rejection reason class, correlation ID
Rate limit triggered	Warning	Limiter name, endpoint, correlation ID
Migration failure	Critical	Exception, attempt count, correlation ID

All six sit at Warning or above, so they cross the Sentry event threshold (BR-U4-06) by construction rather than by coincidence.

Rejection reason classes for the admin bypass — InvalidSignature, Expired, WrongIssuer, NotAdmin, Malformed — never the token itself. The distinction matters: InvalidSignature suggests forgery, while Expired is usually an administrator with a stale tab.

---

Frontend build-time values

Variable	Purpose	Absent behaviour
VITE_API_BASE_URL	API origin	Same-origin (BR-U4-22)
VITE_SENTRY_DSN	Frontend Sentry project	Sentry skipped (BR-U4-26)
VITE_APP_ENV	Environment tag	Untagged
VITE_UMAMI_SCRIPT_URL	Umami script origin	Umami not loaded
VITE_UMAMI_WEBSITE_ID	Per-environment website ID	Nothing rendered (BR-U4-28)
VITE_APP_TITLE	Existing; unchanged	Defaults to SlpModularCms

Why these force two build artifacts (D-15): Vite bakes them into the bundle at build time, so one dist/ cannot carry both the test and production website IDs or environment tags. The CI workflow therefore produces one artifact per environment.

Frontend config model change

AppConfig.apiBaseUrl gains one new legal value: the empty string, meaning same-origin. Its Zod schema becomes "empty string or valid absolute URL" — relaxed by exactly one case, not loosened to accept anything (BR-U4-24).

---

Persistence Summary

Question	Answer
New tables?	None
New migrations?	None
New configuration sections?	One backend section (Observability); frontend variables are build-time
New endpoints?	One — the anonymous Sentry tunnel
Secrets stored?	None. The DSN is not a standing credential and comes from environment variables
Data sent to third parties?	Error events to Sentry, page views to self-hosted Umami. Credentials scrubbed per BR-U4-13