> 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/backend.md).

# Backend & Data Layer

The cloud backend is enabled. Postgres holds all account-scoped state, and every public table ships row-level security plus explicit grants in the same migration.

## Tables

| Table                                   | Holds                                             | Read access                     |
| --------------------------------------- | ------------------------------------------------- | ------------------------------- |
| `profiles`                              | Display name, region, disclosure acknowledgements | Owner only                      |
| `user_roles`                            | `admin` / `moderator` / `user` grants             | Owner + admins                  |
| `linked_wallets`                        | Wallet addresses linked to an account             | Owner only                      |
| `siwe_nonces`                           | Sign-in challenges                                | Server only (no policies)       |
| `watchlists`, `watchlist_items`         | Persisted symbol lists                            | Owner only                      |
| `alert_rules`                           | Price / score / halt / corporate-action rules     | Owner only                      |
| `alert_events`                          | Fired alerts and acknowledgements                 | Owner reads, owner acknowledges |
| `transaction_records`                   | Signed swap history with receipts                 | Owner reads, owner inserts      |
| `ai_insights`                           | Cached Reality Check verdicts                     | Server only                     |
| `ai_usage`                              | Per-user model usage counters                     | Owner reads                     |
| `asset_cache`, `corporate_action_cache` | Public registry / corporate-action cache          | Public read                     |
| `audit_events`                          | Security-relevant actions                         | Admins only                     |

## Security invariants

* Roles live in `user_roles`, never on a profile row, and are read through a `SECURITY DEFINER` `has_role()` helper kept out of the public API schema.
* `siwe_nonces` and `ai_insights` have **no** policies — they are reachable only from trusted server code.
* `alert_events` and `transaction_records` grant no `UPDATE`/`DELETE` beyond acknowledgement, so history is append-only from the client's perspective.
* `profiles` rows are created by a trigger on signup; `handle_new_user()` and `purge_expired_siwe_nonces()` are not executable by `anon`/`authenticated`.
* Amounts in `transaction_records` are stored as `text` base-units with a regex validation trigger — no float precision loss on large token amounts.

## Access pattern

There are no Edge Functions. All backend work goes through typed RPC:

```
component ──▶ src/lib/account.functions.ts ──▶ requireSupabaseAuth ──▶ Postgres (RLS as the user)
```

Server functions that touch a user's rows run under the signed-in user's token, so RLS is the enforcement layer, not application code. Privileged writes (the AI insight cache) use the admin client, imported inside the handler only.


---

# 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/backend.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.