Shipflash logoDocs

Understand The Runtime Architecture

Follow requests, identity, data, provider events, and background work across the boundaries that keep the application secure and maintainable.

On this page

Authenticated application request

  1. 1

    Proxy validates only what routing needs

    The single request proxy validates Supabase claims for session continuity, requests a fresh user only when identity affects routing, allows the Google Identity Services popup on /login and /signup, and delegates route policy outside the provider helper.

    Relevant Product code
    • src/proxy.ts
    • src/lib/supabase/proxy.ts
    • src/lib/request-proxy/route-policy.ts
  2. 2

    Route delegates

    The App Router entrypoint wires framework concerns and calls feature-owned queries, actions, services, or UI composition.

    Relevant Product code
    • src/app/(dashboard)/dashboard/page.tsx
  3. 3

    Server resolves active identity

    Session and RBAC helpers load the profile and evaluate canonical role or feature access on the server.

    Relevant Product code
    • src/lib/auth/session/profile.ts
    • src/lib/auth/rbac/server.ts
  4. 4

    Feature executes the use case

    Feature services enforce business rules and call persistence or isolated provider adapters.

    Relevant Product code
    • src/features/billing/server/services/portal.ts
    • src/features/billing/server/runtime/provider.ts
  5. 5

    UI receives app-owned data

    Feature queries and view models return bounded, masked, application-owned results for rendering.

    Relevant Product code
    • src/features/customers/server/list/page-query.ts
    • src/features/customers/ui/list-page.tsx

External event and background-work path

  1. 1

    Authenticate the caller

    Machine routes bypass the browser session proxy, establish their own request IDs, validate provider signatures, or require the cron bearer secret before work begins.

    Relevant Product code
    • src/proxy.ts
    • src/app/api/webhooks/stripe/billing/route.ts
    • src/app/api/cron/notification-outbox/route.ts
  2. 2

    Claim or deduplicate

    Provider events and queued jobs use durable identifiers and claims so retries do not repeat unsafe work.

    Relevant Product code
    • src/lib/security/webhooks/processing.ts
    • src/features/notifications/server/outbox/services/worker.ts
  3. 3

    Apply domain projection

    Handlers update application-owned billing, notification, content, or retention state without exposing provider payloads to UI code.

    Relevant Product code
    • src/features/billing/server/providers/stripe/webhooks/handler.ts
    • src/features/notifications/server/webhooks/resend/handler.ts
  4. 4

    Record outcome

    Status, attempts, stable identifiers, and useful failure context remain available for retry and operator investigation.

    Relevant Product code
    • src/features/notifications/server/outbox/services/worker.ts
    • src/lib/observe/logging/logging.ts

Sources of truth and projections

ConcernSource of truthProjection or cacheDo not assume
IdentitySupabase Auth user plus the active profile and canonical role.Request session and cached profile reads.A client-submitted profile or hidden control proves identity.
Billing provider stateThe active Stripe or Lemon Squeezy account.Local billing customer, subscription, order, invoice, charge, refund, usage, credit, and entitlement tables.Webhooks arrive once or in order.
Notification deliveryApplication event plus provider delivery result.Outbox, attempts, send logs, and webhook-updated status.A queued record means the message was delivered.
Published contentValidated CMS records and publication state.Rendered pages, metadata, and revalidated route output.A draft or scheduled item is immediately public.
ConfigurationCanonical environment variables and validated database-backed settings.Normalized runtime policy and readiness results.A value displayed in UI is valid for the provider.

Architecture review questions

  • Which module owns the behavior and its vocabulary?
  • Where is identity established and authorization enforced?
  • What is the authoritative record and what is only a projection, cache, or provider snapshot?
  • Can the request, webhook, or job be retried or delivered twice safely?
  • What state is visible after partial failure, and how does an operator recover it?
  • Does a growing read remain bounded, indexed, and filtered in the database?