> For the complete documentation index, see [llms.txt](https://sonic-ai-works.gitbook.io/sonic-networks-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sonic-ai-works.gitbook.io/sonic-networks-docs/sonic-1.0.0-rc-production-architecture/architecture.md).

# Architecture

SONIC 1.0.0-rc.0 monorepo, control planes, durable state and request execution architecture.

SONIC separates creator-facing experience from product authority, commercial state, trust/reconciliation and execution infrastructure.

## Five-plane model

```mermaid
flowchart TB
    E[Experience Plane\nWeb · Wallet · Studio · Marketplace · Releases]
    P[Product Control Plane\nProjects · Versions · Identity · Rights · Policies]
    C[Commercial Plane\nPricing · Sale · Billing · Payments · Usage · Receipts]
    T[Trust Plane\nProvenance · Ownership · Verification · Settlement · Audit]
    X[Execution Plane\nAI · PostgreSQL · Redis · Helius · Solana · Token-2022]
    E --> P --> C --> T --> X
```

## Monorepo contract

```
apps/
  web/       public product and discovery
  wallet/    role-aware Token Management and account application
  api/       Fastify server authority for /api/v1 and /ws/v1
  worker/    confirmation, settlement, reconciliation and background jobs

packages/
  contracts/       canonical IDs, states, Zod schemas
  sdk/             typed SONIC API client
  auth/            account sessions + independent wallet proofs
  config/          environment, cluster, readiness validation
  database/        PostgreSQL + Prisma
  domain/          state machines and invariants
  sale/            Sale Release, eligibility and signed quotes
  payments/        atomic-value payment utilities
  payment-kernel/  transaction construction boundary
  wallets/         wallet identity and cluster helpers
  market-data/     Pyth/Birdeye/provider aggregation
  realtime/        durable event projection + polling fallback
  checkout/        checkout lifecycle contracts
  marketplace/     listing/right/order contracts
  studio/          generation/version contracts
  queue/           outbox claim/retry/recovery
  storage/         S3/R2-compatible media storage
  cache/           cache boundary
  solana/          RPC/mint/program validation
  ui/              semantic design tokens
  observability/   logs, metrics, traces and audit correlation
```

## Server-authoritative request path

```mermaid
sequenceDiagram
    participant UI as Web / Wallet
    participant API as /api/v1
    participant IAM as Auth + Access
    participant DB as PostgreSQL
    participant EXT as Provider / Solana
    participant W as Worker

    UI->>API: authenticated request
    API->>IAM: resolve principal, role, entitlement
    IAM-->>API: authorization decision
    API->>DB: durable operation + audit + outbox
    API-->>UI: operation ID / current state
    W->>EXT: execute external effect when required
    EXT-->>W: provider/chain result
    W->>DB: verify, settle, reconcile
    DB-->>UI: realtime projection / polling state
```

## Durable identifiers

Critical workflows carry stable IDs for request, account, user, session, wallet, Sale Release, eligibility decision, purchase intent, quote, transaction, receipt, generation job, upload, project version and reconciliation attempt.

Display strings are never used as durable identity. Slugs are human-readable routing aids and may not replace immutable IDs in authorization or accounting.

## State ownership

Frontend state may render loading, optimistic selection and local drafts. It may not manufacture backend success. Generation progress, payment state, sale allocation, subscription status and reconciliation are derived from durable server state.

{% hint style="success" %}
A confirmed Solana transaction is not the same as a reconciled commercial operation. SONIC preserves the distinction through explicit transaction, settlement, reconciliation and receipt states.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://sonic-ai-works.gitbook.io/sonic-networks-docs/sonic-1.0.0-rc-production-architecture/architecture.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.