> For the complete documentation index, see [llms.txt](https://docs.pokefi.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pokefi.xyz/technical-reference/architecture.md). # Architecture Overview PokeFi is a web application with a Solana-native settlement layer and an off-chain service layer for valuation, custody integration, indexing, and transparency. The design separates concerns cleanly: fund custody and loan settlement live on-chain, while metadata, valuations, and fast reads live off-chain, with the on-chain state always the source of truth for anything that moves money or collateral. *** ## Stack | Layer | Technology | Purpose | | ------------------- | ------------------------------------------------------------------------- | --------------------------------------------------- | | Blockchain | Solana | Loan settlement, USDC transfer, title-token escrow | | On-chain programs | Rust + Anchor | Loan lifecycle, escrow, default settlement | | Title token | SPL token / Metaplex metadata | On-chain representation of a vaulted card | | Frontend | Next.js 16 (App Router, Turbopack), React 19, TypeScript, Tailwind CSS v4 | Web application | | Wallet integration | Solana Wallet Adapter | Phantom, Backpack, Solflare support | | Database and RPCs | Supabase (Postgres) | Off-chain index, profiles, atomic money-moving RPCs | | Valuation service | PokeFi Reference Price engine | Blended comps and population pricing | | Custody integration | Vault partner API | Intake, authentication, mint, redemption sync | | Stablecoin | Native SPL USDC | The unit of account for every loan | *** ## On-Chain vs Off-Chain PokeFi maintains a deliberate split between what is settled on-chain and what is served off-chain. ### On-chain (Solana) Everything that affects custody of funds or collateral is on-chain: * Loan settlement: funding, repayment, default, cancellation * USDC transfers between lender, borrower, and escrow * The title token and its escrow * The events emitted at each loan state transition ### Off-chain (Supabase and services) Data that is large, frequently read, or non-custodial is served off-chain: * Profiles and verification (KYC) status * The card catalog: grader, certificate, set, grade, population, photos, vault reference * Valuation history (the Reference Price and the comps behind it) * An indexed mirror of loan state and the append-only event ledger, for fast reads and the public explorer The on-chain state is authoritative. Off-chain data is derived from or supplementary to it. In any discrepancy, the program state and the settled transactions take precedence. *** ## The Data Model The off-chain domain is organized around a small set of tables. The full schema lives in the Supabase migration; the core entities are: | Entity | Represents | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `profiles` | A user, with a role (`borrower`, `lender`, or `both`) and a `kyc_status` | | `cards` | A vaulted graded card: grader, certificate, grade, population, vault reference, title-token mint, and status (`vaulted`, `escrowed`, `redeemed`, `in_liquidation`) | | `valuations` | The history of Reference Prices for a card, each with the comps and population it was derived from | | `loans` | The core entity: one row covers the full lifecycle from `open` through `funded` to `repaid`, `defaulted`, or `cancelled` | | `loan_events` | An append-only ledger of every state transition, powering the public explorer | | `repayments` | Individual repayment records, supporting partial repayment | | `pool_deposits` | Reserved for the post-beta curated lender pool | A card carries a denormalized `reference_price_usdc` that is kept in sync with its newest valuation, and a partial unique index enforces that a card can only back one live loan (`open` or `funded`) at a time. *** ## Money-Moving RPCs Actions that move money or collateral run through atomic database RPCs (Postgres `SECURITY DEFINER` functions), so that a state change and its ledger event either both happen or neither does. The application calls these rather than mutating rows directly. The three core RPCs mirror the on-chain instructions: ### `fund_loan` Called when a lender funds an open request. In a single transaction it: * Validates the loan is `open` and that the lender is not the borrower * Validates the chosen APR does not exceed the borrower's maximum * Computes fixed-at-origination interest: `principal × APR × (duration ÷ 365)` * Computes loan-to-value against the card's Reference Price * Sets the total repayment, the start, and the maturity date * Sets the loan to `funded` and the card to `escrowed` * Records a `funded` event ### `repay_loan` Called when the borrower repays, in full or in part. It records the repayment, sums cumulative repayments, and logs a `repayment` event. When cumulative repayments reach the total repayment amount, it marks the loan `repaid`, returns the card to `vaulted`, and logs a `repaid` event. ### `claim_default` Called after maturity passes without full repayment. It validates the loan is `funded` and that maturity has elapsed, marks the loan `defaulted`, transfers card ownership to the lender, and logs a `defaulted` event. A trigger also logs a `requested` event whenever a new loan row is created, so the ledger captures the full lifecycle from the first moment. *** ## Access Control Row-level security enforces the transparency-versus-privacy split: * **Public read.** Cards, valuations, loans, and loan events are readable by anyone. Transparency is a brand pillar. * **Owner-scoped writes.** A card owner manages their own cards. A borrower can create and cancel their own `open` loan requests. Repayments and pool deposits are visible to the parties involved. * **RPC-gated money movement.** Funding, repayment, and default settlement never happen through direct row writes. They go through the `SECURITY DEFINER` RPCs above, which run the validation and event logging atomically. *** ## Transparency Layer Because the `loan_events` ledger is append-only and public-read, it powers a human-readable explorer: every loan, its collateral card, the terms, the funding, each repayment, and any default, all linkable and auditable. This is "don't trust, verify" presented with the clarity of a financial product rather than a raw block explorer. See [Solana Programs](/technical-reference/solana-programs.md) for the on-chain side of the same events. *** ## Identity and Authentication PokeFi uses **wallet-based authentication**. A user's Solana wallet is their identity, and sessions are established by signing a challenge message. Because PokeFi is a real-money lending product, wallet identity is paired with an off-chain **KYC status** on the profile, which must be verified before a user can fund a loan or have one funded. *** ## Environments | Environment | Solana cluster | Notes | | ----------- | -------------- | --------------------------------------------------------- | | Development | Devnet | Test SOL and USDC via faucets; no real value | | Staging | Devnet | Mirrors production infrastructure for pre-release testing | | Production | Mainnet | Live loans with real USDC and real collateral | Beta operates on **mainnet** with real USDC and real vaulted cards. Devnet access is available to developers building integrations. --- # 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.pokefi.xyz/technical-reference/architecture.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.