> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rodyne.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture

> A high-level map of Rodyne services, trust boundaries, and durable provider work.

Rodyne is a TypeScript monorepo with independent web, API, authentication, ingress, identity-linking, member, and worker services.

## Services

| Service        | Responsibility                                                               | Local port |
| -------------- | ---------------------------------------------------------------------------- | ---------: |
| `apps/web`     | Staff dashboard, onboarding, account management, and host-scoped BFF.        |       3000 |
| `apps/api`     | Tenant API, permissions, idempotent writes, billing management, and OpenAPI. |       3001 |
| `apps/auth`    | Better Auth, provider OAuth, PKCE, and single-use handoffs.                  |       3002 |
| `apps/ingress` | Raw Stripe webhooks and signed Studio connector ingestion.                   |       3003 |
| `apps/connect` | Member identity linking, isolated from staff sessions.                       |       3004 |
| `apps/dash`    | Member-safe personal record portal with its own session.                     |       3005 |
| `apps/worker`  | PostgreSQL queue, Discord gateway, provider jobs, and aggregation.           |    Private |

## Shared packages

Packages provide configuration, contracts, permission resolution, Drizzle schema/database access, authentication helpers, provider clients, structured logging, and UI primitives.

## Request and job flow

```text theme={null}
Browser / Discord / Studio
          │
          ▼
Web BFF / API / signed ingress
          │
          ├── permission + tenant + input checks
          ├── transaction + audit + idempotency
          ▼
PostgreSQL durable queue
          │
          ▼
Worker → Discord / Roblox / Stripe / configured providers
          │
          └── read-back, target outcome, retry or operator review
```

The queue uses PostgreSQL row locking and leases, so it survives process restarts without Redis. Provider work is serialized where duplicate or out-of-order writes would be unsafe.

## Trust boundaries

* Browser input never supplies authoritative workspace roles or provider membership.
* OAuth audiences and host-scoped sessions are separated by product surface.
* Studio ingress signs the exact JSON bytes with an experience-scoped secret.
* Provider credentials stay in server configuration or protected storage.
* Cross-workspace and restricted-record reads are checked in the API and database queries.

## Data model principles

* Reviewed SQL migrations evolve operational constraints.
* Append-only audit and history structures preserve important changes.
* Identity ownership is distinct from imported or discovered member records.
* Queued work records requested, desired, and observed provider state separately.

## Guided walkthrough

<Frame caption="The user-visible Activity model reflects the architecture's durable request, worker, and provider boundaries.">
  <img src="https://mintcdn.com/rodyne/3VLEvtRzxXCeXuB_/assets/screenshots/activity-main.png?fit=max&auto=format&n=3VLEvtRzxXCeXuB_&q=85&s=aa34e91db4b6746d0f6a4291cb29f70f" alt="Rodyne Activity page reflecting service and provider job boundaries" width="990" height="742" data-path="assets/screenshots/activity-main.png" />
</Frame>

The screenshot above is from the live Rodyne product. Use it to orient yourself, but rely on the current record state and live provider checks when operating the workspace.

## Operating procedure

<Steps>
  <Step title="Trace the ingress">
    Identify browser, Discord, Studio, webhook, or member portal as the trust boundary.
  </Step>

  <Step title="Resolve tenant and actor">
    Authenticate the correct audience and bind every operation to its workspace.
  </Step>

  <Step title="Commit durable intent">
    Persist idempotency, policy revision, and target information before provider work.
  </Step>

  <Step title="Execute in the worker">
    Recheck authority and current state immediately before external mutation.
  </Step>

  <Step title="Read back and audit">
    Store the provider-confirmed outcome and expose it to the originating record.
  </Step>
</Steps>

## Acceptance checks

| Check    | Ready when                                     | If it is not ready                      |
| -------- | ---------------------------------------------- | --------------------------------------- |
| Audience | Session belongs to the intended application    | Reject cross-audience cookies or tokens |
| Tenant   | Every query and job is workspace-scoped        | Fail closed                             |
| Provider | Success is backed by read-back where supported | Keep outcome partial or uncertain       |

## Failure recovery

When debugging across services, carry correlation and record IDs instead of secrets or raw payloads. The durable job and audit record should reconstruct the control flow.

## Continue the workflow

<CardGroup cols={2}>
  <Card title="Local development" href="/developers/local-development" icon="laptop" />

  <Card title="Outcomes and jobs" href="/reference/outcomes-and-jobs" icon="activity" />
</CardGroup>