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

# System Overview

## Stack

| Layer     | Technology                                              |
| --------- | ------------------------------------------------------- |
| Framework | TanStack Start v1 (React 19, SSR)                       |
| Build     | Vite 7                                                  |
| Routing   | TanStack Router (file-based, `src/routes`)              |
| Data      | TanStack Query                                          |
| Styling   | Tailwind CSS v4 via `src/styles.css` `@theme` tokens    |
| Chain     | wagmi + viem, chain ID `4663`                           |
| Math      | `decimal.js` + viem unit helpers                        |
| Server    | `createServerFn` RPC, edge runtime                      |
| Tests     | Vitest                                                  |
| Database  | Postgres (cloud backend) with RLS on every public table |
| AI        | AI gateway, `google/gemini-3.6-flash`, bounded schema   |

There is no Express server, no separate API service, and no client-side secret. Server logic is same-origin RPC, so there is no CORS surface to defend.

## Request flow

```
 browser                      edge server                    upstream
 ───────                      ───────────                    ────────
 route loader ──ensureQueryData──▶ *.functions.ts
                                      │ Zod validate
                                      │ rate limit (per IP)
                                      ▼
                                  *.server.ts ──────▶ Robinhood market data
                                      │        ──────▶ 0x Swap API (chain 4663)
                                      │        ──────▶ Robinhood Chain RPC
                                      ▼
                              sanitized DTO (market-types.ts)
 useSuspenseQuery ◀────────────────────┘
 wallet signs tx ──────────────────────────────────▶ Robinhood Chain
```

Only the wallet signs. The server never holds a key, never submits a transaction, and never returns raw upstream error bodies.

## Data sources

| Source                                   | Used for                                             | Cache                            |
| ---------------------------------------- | ---------------------------------------------------- | -------------------------------- |
| `GET /rhj/assets`                        | Canonical stock-token registry                       | Cached; filtered to chain `4663` |
| `GET /rhj/prices/{symbol}`               | Underlying bid/ask, volume, halt state               | 15s                              |
| `api.0x.org/swap/allowance-holder/price` | Indicative executable price                          | Not cached                       |
| `api.0x.org/swap/allowance-holder/quote` | Firm quote + calldata                                | Not cached                       |
| Robinhood Chain RPC                      | Block height, latency, balances, `decimals`/`symbol` | Short-lived                      |

## Resilience contract

Every live surface implements: **loading, empty, stale, offline, upstream-error, retry, last-updated**.

Three rules make the UI trustworthy:

1. **No mock fallbacks.** A failed request renders a degraded state, never a plausible number.
2. **Every number is attributable.** Timestamps and sources accompany displayed values.
3. **No simulated success.** A transaction is "confirmed" only after a receipt.

## Account-scoped data

The cloud backend is enabled. Account state (profiles, wallets, watchlists, alerts, trade history, AI cache) lives in Postgres behind row-level security and is reached only through typed RPC — there are no Edge Functions. See [Backend & Data Layer](/bubblegum-reality-docs/architecture/backend.md).

## Deliberate non-goals

No custody, no advice, no mock fallbacks, and no affiliation with Robinhood. See [Roadmap](/bubblegum-reality-docs/operations/roadmap.md) for what is still unbuilt.


---

# 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://bubblegum-reality.gitbook.io/bubblegum-reality-docs/architecture/overview.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.