> For the complete documentation index, see [llms.txt](https://docs.usefarlight.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.usefarlight.com/architecture/platform.md). # Inside the platform The Farlight platform at usefarlight.com/platform, covering its routes, the Privy and Supabase sign-in bridge, the database behind it and its instrument-panel interface. Farlight's reference front-end and relayer ship together as one application, the platform, served at `/platform` on the main site. It is built with Next.js, authenticates with Privy and keeps the shared order book in Supabase. The interface is an instrument panel: dark, quiet and built around live readouts. None of those readouts is hardcoded. Markets, prices, parameters, requests, offers, loans and events all come out of Supabase, so a user always sees the current state of the book. ## Routes | Route | Who can use it | Contents | | --------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `/platform` | Anyone | Telemetry: protocol statistics, the market table with tier limits and live indicative rates, and the open requests | | `/platform/borrow` | Signed-in users | A form for creating a borrow request (collateral, principal, maximum APR, term, deadline) with live LTV, health factor and fee; the user's own requests with their fill coverage from the book; settlement | | `/platform/lend` | Anyone; more when signed in | The public book of open requests; posting standing or targeted offers with flags; the user's own offers with remaining capacity and a cancel action | | `/platform/positions` | Signed-in users | Loans the user has taken (debt, accrued interest, health, repay, top up) and the slices the user holds | | `/platform/explorer` | Anyone | The Observatory: the loan registry with each syndicate and its flight log of events, concentration by token measured against the caps, and the parameters in force | | `/platform/settings` | Signed-in users | The user's profile and the eligibility attestations issued to their wallet | Three of the terms above recur throughout the product. Telemetry is the set of live protocol readouts: statistics, concentration and the parameters in force. The Observatory is the public loan explorer, where anyone can see every loan. A flight log is the event history of a single loan, each entry linked to its Blockscout transaction. The deadline on a borrow request is its launch window, the time by which the request must fill. ## Sign-in, and the bridge from Privy to Supabase Privy handles sign-in by email, by Google or with any EVM wallet. Anyone who arrives without a wallet receives an embedded one on Robinhood Chain, and that address signs their requests and offers from then on. Supabase knows nothing about Privy, so the two are joined on the server: 1. Public data (markets, prices, parameters, the order book, loans, slices, events) is read straight from the browser with the anon key. 2. Anything done as a user (reading the profile or attestations, posting requests and offers, cancelling, settling, repaying, topping up) is sent to `POST /api/platform/db` with the Privy access token attached. 3. That route verifies the token with `@privy-io/server-auth`, validates the arguments, and runs the operation through a service-role Supabase client that carries the verified user id in an `x-farlight-actor` header. The database function `app_user_id()` respects that header only on service-role requests, so the ownership checks inside the `security definer` functions see the real user. The service-role key never leaves the server. Row-level security still bounds what the anon key can read, and every write still goes through the database functions that enforce the matching rules. ## Database schema The schema in `supabase/schema.sql` mirrors the on-chain design one table at a time: | Table | On-chain counterpart | Written by | | -------------------------------- | ----------------------------------------------------------- | ----------------------------------- | | `markets` | Token and tier configuration in `PolicyController` | Service role | | `oracle_prices` | `PriceGate.quote()` | Service role (a keeper or cron job) | | `protocol_params` | `PolicyController` parameters plus the deployment addresses | Service role | | `attestations` | `AttestationStore` | Service role (the KYC issuer) | | `borrow_requests` | The relayer's book of requests | Borrowers, via the API route | | `offers` | The relayer's book of offers (signed EIP-712 messages) | Lenders, via the API route | | `loans`, `slices`, `loan_events` | `LoanDesk` state | Database functions only | Each state transition is a `security definer` function: `settle_request`, `cancel_request`, `cancel_offer`, `record_repayment` and `record_collateral_added`. That is what lets the database apply the matching rules (term, APR ceiling, tier scope, capacity, minimum fill, expiry, full coverage) in exactly the way `LoanDesk` applies them on-chain. ## Signing typed data Requests and offers are signed as EIP-712 typed data. The struct layout and the domain (`Farlight` / `1` / chain id / `LoanDesk`) match `contracts/src/libraries/IntentHash.sol`. The typed-data hash is stored beside the signature so that a relayer, or the contract itself, can verify it later. Because signing goes through Privy's `signTypedData`, it costs no gas. ## Settlement, on-chain or in the book Contract addresses are held in the `deployment` row of `protocol_params`. When `LoanDesk` is present there, settling a request sends a real `originate` transaction from the user's Privy wallet through viem's `writeContract`, and the transaction hash is stored on the loan. When it is absent, the settlement is recorded in the book alone and the loan is labelled accordingly. Matching is greedy by APR, in the order the relayer documentation sets out. ## Look and feel The platform and the marketing site share one design system, so they read as a single product. The page ground is Void (`#05070d`), sections and panel grounds sit on Deep (`#0b1020`), and raised panels and cards on Hull (`#121a2e`), with Hairline (`#223052`) for borders, rules and grid lines. Primary text is Starlight (`#e8eef9`), secondary text Dust (`#9aa8c4`), and muted labels and captions Faint (`#5f6d8a`). Beacon (`#7fd3ff`) is the one accent, used for actions, links, the mark and live indicators; on light surfaces it becomes Beacon deep (`#1d8fd1`). Signal (`#f2b544`) marks warnings and margin calls, Verdant (`#4fd38a`) healthy figures, and Flare (`#ff5c5c`) liquidation and loss. Documents and long reading use Paper (`#f4f7fc`) with Deep as the text colour. Headings, labels and buttons are set in Sora, body copy in Instrument Sans, and every number, address and hash in Geist Mono with tabular figures, since the numbers are the point of every screen. Panels carry hairline frames with crosshair ticks at their corners; corners are squared or lightly rounded, never pills. The only ornament is fine grid lines, orbit arcs and trajectory curves. Motion is slow: instruments count up on load and telemetry ticks, and nothing bounces or flashes. The two applications share the same `.panel` and `.btn` primitives. ## Configuration Setup is described in `supabase/README.md` and `.env.example` at the root of the repository. When an environment variable is missing, the platform displays a setup notice naming it rather than failing silently. --- # 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.usefarlight.com/architecture/platform.md?ask=&goal= ``` `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.