> 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/documentation/developers/architecture-and-runtime/full-platform-architecture.md).

# Full Platform Architecture

Canonical SONIC v1.0.0 monorepo and runtime architecture across public web, authenticated applications, API, realtime, identity/access, mail, AI, finance and Solana.

SONIC separates presentation, authenticated product UX, server authority, identity/access, AI/media execution, commerce/finance, protocol execution, realtime delivery, mail/notifications, events and ledgers.

## Application topology

```
apps/
├── web                 public website / discovery
├── frontend            authenticated application shell
├── backend             /api/v1 server authority
├── realtime            /ws/v1 event delivery
├── worker              durable jobs / reconciliation
├── indexer             Solana/provider projections
├── docs                developer-owned docs tooling
└── mobile              Expo/React Native client

packages/
├── types               canonical contracts
├── auth                Clerk/session adapters
├── identity            SONIC user/workspace identity
├── access              RBAC + ABAC + AAL + entitlements
├── permissions         permission catalog
├── mail                provider-independent transactional mail
├── config              validated runtime configuration
├── transactions        transaction intents/plans/attempts
├── solana-rpc          cluster-aware RPC boundary
├── program-clients     generated/typed Solana clients
└── observability       logs, traces, metrics, audit correlation

programs/               SONIC Solana programs
workers/                domain workers and provider callbacks
```

## Request path

```
client
→ Clerk-authenticated session
→ SONIC identity mapping
→ workspace membership
→ role + permission + entitlement resolution
→ authorize(principal, action, resource, environment)
→ durable domain operation
→ provider/chain execution where required
→ verification
→ settlement/reconciliation where required
→ /ws/v1 event + audit receipt
```

`DEVELOPER` is a first-class workspace role but cannot bypass entitlement, resource, AAL or risk checks.

## Mail path

Transactional email is asynchronous and non-authoritative:

```
account/bootstrap event
→ transactional outbox
→ mail worker
→ template render
→ Resend/Postmark adapter
→ provider message ID
→ delivery event / retry / terminal failure
```

Signup must not be rolled back merely because a welcome email provider is unavailable. Verification/security-critical messages use their own explicit delivery policy and never expose auth/session secrets in logs.

## Realtime path

```
HTTP mutation
→ durable commit + outbox
→ event bus
→ /ws/v1 authorized topic
→ client projection refresh
```

WebSocket events are hints/projections, never permission or settlement authority.

## Value-moving invariant

```
VALIDATE → CREATE OPERATION → QUOTE → INTENT → SIMULATE → AUTHORIZE
→ SIGN → SUBMIT → CONFIRM → VERIFY EFFECT → SETTLE → RECONCILE
```

## Platform invariant

```
separate apps
+ shared contracts
+ Clerk session authority
+ SONIC identity
+ server-derived access
+ durable operations
+ async mail/realtime
+ verified economic effects
= SONIC v1.0.0 architecture
```


---

# 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/documentation/developers/architecture-and-runtime/full-platform-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.