Identity

Route flow contract

1. `/profile` requires an authenticated session. Anonymous users are redirected to sign-in with return continuation.
2. Session entry calls ensureUserProfileForSession, guaranteeing profile row existence before render.
3. Public route `/<username>` resolves normalized username and loads viewer-aware projection.
4. Private profiles return owner-only detail while preserving public route boundaries.

Identity state assembly

1. Profile root data loads from `user_profiles` with normalized social/contact fields.
2. Follow relationship is resolved to connection state (`self`, `mutual`, `following`, `follower`, `none`).
3. Originals merge creator-owned records and verified-owned collected records.
4. Anchor metadata resolves claim hash, media envelope, context preset, and download policy flags.
5. Proof state resolves Groth16 digest and Poseidon hash through zk cache/API pathways.
6. Visibility policy is applied per receiz ID and ownership key, then filtered for public projection.
7. Witness metrics are rolled from analytics and realtime witnessed duration rollups.

Tracked event contract

Event taxonomy is typed and scope-classified (`profile`, `original`, `stream`, `commerce`) before storage.

Windows + timeline ranges

• Every key overview metric includes `all`, `d90`, `d30`, `d7`, `d1` windows.
• Timeline outputs support `30m, 6h, 24h, 7d, 30d, 90d, 1y, 3y` ranges for short-term and long-horizon analysis.
• `/profile/analytics` renders these ranges with interactive chart switching.

User-facing analytics surfaces

• `/profile` inline stats (followers/witnesses, streams, views, completion, witnessed seconds) with periodic/realtime refresh hooks.
• `/profile/analytics` full owner analytics console with funnel, top originals, traffic intelligence, and multi-range charts.
• Per-original detail viewer instrumentation for impressions, opens, stream actions, download clicks, and paid flow transitions.

Developer instrumentation notes

• Ingestion endpoint: `POST /api/profile/analytics/track` with strict event-name validation and bounded payload fields.
• Client helper: `trackProfileAnalyticsEventClient(...)` uses sendBeacon/fetch fallback and session dedupe via `oncePerSessionKey`.
• Server aggregation: `loadProfileAnalyticsForOwner(...)` computes overview, stream, commerce, funnel, traffic, timelines, originals, recent activity.
• Schema support: `user_profile_analytics_events` plus `user_profile_witnessed_rollups` trigger-based duration aggregation.
• Realtime publication exists for analytics events and witnessed rollups to support live profile stat freshness.

Data model primitives

Hard constraints to enforce

• Username contract: ^[a-z0-9_]{3,24}$, lowercase canonicalization, reserved-word rejection.
• Profile patch fields are length-bounded and URL-normalized to http/https only.
• Media + original flows verify content size and SHA-256 before durable publish paths.
• Visibility updates enforce ownership checks and entitlement checks for verified-owned showcase.
• Paid downloads require verified Stripe checkout session metadata binding before byte release.
• Receiz challenge-confirm purchase flow cryptographically binds buyer intent before paid release execution.
• Derivative media generation (image variants/posters) is size-bounded, validated, and policy-controlled.
• Analytics ingestion validates event enum and bounds payload fields for stable rollup quality.

Example: profile mutation

PATCH /api/profile/me
content-type: application/json

{
  "username": "operator_prime",
  "displayName": "Operator Prime",
  "bio": "Canonical issuer profile",
  "websiteUrl": "https://example.org",
  "socialXUrl": "https://x.com/operator_prime",
  "isPrivate": false
}

Example: analytics event

POST /api/profile/analytics/track
content-type: application/json

{
  "username": "operator_prime",
  "event": "original_open",
  "receizId": "00000000-0000-0000-0000-000000000000",
  "source": "profile_public_page",
  "durationSeconds": 12.4,
  "meta": {
    "ownershipKind": "creator",
    "layout": "single"
  }
}