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

# Architecture

A deliberately small stack: one Next.js app that reads Derive's public API and asks the user's wallet to sign, plus two tiny Cloudflare Workers — the waitlist API and the pre-launch page on ichigeki.app. No backend of record, no database of user funds or positions — Derive Chain is the state.

## Stack

| Layer           | Choice                                                                                   |
| --------------- | ---------------------------------------------------------------------------------------- |
| Framework       | Next.js (App Router), TypeScript strict                                                  |
| Styling         | Tailwind CSS v4 — design tokens in `src/app/globals.css`, rules in `DESIGN.md`           |
| Wallet          | wagmi v3 + viem (Robinhood Chain, Arbitrum, Derive Chain defined in `src/lib/chains.ts`) |
| Data            | TanStack Query v5 polling Derive's public REST API                                       |
| Waitlist API    | Cloudflare Worker (`workers/api`)                                                        |
| Pre-launch page | Cloudflare Worker (`workers/www`) on ichigeki.app                                        |
| Hosting         | Vercel (app), Cloudflare (workers), GitBook (docs)                                       |

## Repo layout

```
.
├── docs/                    # this documentation (GitBook Git Sync)
├── design/                  # approved brand canvas
├── DESIGN.md                # distilled brand rules — read before touching UI
├── src/
│   ├── app/                 # App Router pages, layout, globals.css (tokens)
│   ├── components/
│   │   ├── brand/           # Wordmark, Seal
│   │   ├── layout/          # Header, Footer
│   │   └── wallet/          # ConnectButton
│   ├── hooks/
│   │   ├── useOptionsChain.ts    # instruments + live strike ladder
│   │   └── useExpiryCountdown.ts # the clock
│   └── lib/
│       ├── constants.ts     # fixed brand copy, product truth-in-labeling
│       ├── format.ts        # fmtUsd, fmtStrike, fmtExpiryUtc, …
│       ├── chains.ts        # Robinhood Chain, Derive Chain viem definitions
│       ├── wagmi.ts         # wagmi config
│       └── derive/
│           ├── client.ts        # public API transport
│           ├── types.ts         # API shapes (numbers stay strings at the edge)
│           ├── instruments.ts   # fetch/filter, nearest expiry, isZeroDte
│           ├── ladder.ts        # quote-driven strike ladder
│           └── orders.ts        # submitOrder, isTradingEnabled (Phase 2 gate)
└── workers/
    ├── api                  # Cloudflare Worker — waitlist endpoint
    └── www                  # Cloudflare Worker — coming-soon page on ichigeki.app
```

## Data flow

```
Derive public REST (api.lyra.finance)
        │  get_instruments (60s) · get_ticker (5s, bounded set)
        ▼
src/lib/derive/*            pure functions, no React
        ▼
src/hooks/useOptionsChain   TanStack Query: cache, polling, abort
        ▼
components                  ladder rows, countdown, order footer
        ▼
user's wallet               signs orders (Phase 2+) and funding txs
```

Two conventions worth knowing before contributing:

* **Numbers are strings at the edge.** Derive returns numeric fields as strings; `src/lib/derive/types.ts` keeps them that way, and conversion happens in the UI/format layer. Do not parse inside the transport.
* **The ladder is quote-driven.** `buildLadder` prefers strikes with a live ask, ranks by distance from index, caps rows, and backfills unquoted strikes as dimmed rows. See [Liquidity](/product/liquidity.md) for the product rationale.

## The Cloudflare workers

Two small workers, neither of which holds user funds, keys, or trading state:

* **`workers/api`** — the pre-launch waitlist API. The Next.js app points at it via `NEXT_PUBLIC_WAITLIST_API`; deployment details live in `workers/api/README.md`.
* **`workers/www`** — the branded coming-soon page served on ichigeki.app and www while the app itself is refined privately.

## Design system

`DESIGN.md` is normative: palette tokens (`sumi`, `paper`, `strike`, `loss`, …), the three typefaces, the −4.6°/−45° cut angles, and the motion budget (≥5s stillness per ≤200ms action). Components use Tailwind token classes only — raw hex in a component is a review failure. Strike green appears only at selection, execution, profit and settlement; red only for losses and expiry.


---

# 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://docs.ichigeki.app/developers/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.