# Architecture Overview

PepFund is a web application with a Solana-native backend. The platform separates concerns clearly: business logic and financial state live entirely onchain in Solana programs; off-chain infrastructure handles metadata, indexing, and user interface delivery.

***

## Stack

| Layer               | Technology                                     | Purpose                                         |
| ------------------- | ---------------------------------------------- | ----------------------------------------------- |
| Blockchain          | Solana Mainnet                                 | Program execution, fund custody, token issuance |
| Smart Contracts     | Rust + Anchor Framework                        | Campaign logic, escrow, milestone gating        |
| Token Standard      | SPL Token-2022                                 | Research token issuance with extensions         |
| Frontend            | Next.js (App Router), TypeScript, Tailwind CSS | Web application                                 |
| Wallet Integration  | Solana Wallet Adapter                          | Phantom, Backpack, Solflare support             |
| Permanent Storage   | Arweave                                        | Milestone evidence, research documents          |
| RPC and Indexing    | Helius                                         | Solana RPC, webhook-based state indexing        |
| Off-chain Database  | Supabase                                       | Campaign metadata, researcher profiles, images  |
| Researcher Identity | ORCID OAuth                                    | Credential verification                         |

***

## Onchain vs Off-Chain Data

PepFund maintains a deliberate split between what is stored onchain and what is stored off-chain.

### Onchain (Solana)

Everything that affects financial state or backer rights is onchain:

* Campaign funding state (goal, amount raised, deadline, current milestone)
* Individual contribution records
* Milestone state (submitted, disputed, released)
* Arweave content hashes for milestone evidence
* Research token mint and distribution
* Escrow balances
* Flag records and governance actions

### Off-Chain (Supabase + Arweave)

Data that is large, frequently updated, or non-financial is stored off-chain:

* Campaign text, images, and long-form content (Supabase)
* Researcher profiles and biographies (Supabase)
* Milestone evidence files (Arweave, content-addressed and permanent)
* Indexed campaign state for fast reads (Supabase, synced via Helius webhooks)

The onchain state is always the source of truth. Off-chain data is derived from or supplementary to what is on Solana. In the event of any discrepancy, the program state takes precedence.

***

## Request Flow

A typical backer contribution flows as follows:

```
Browser
  │
  ├── Reads campaign metadata from Supabase (fast, no wallet required)
  │
  ├── Reads live funding state from Helius RPC (onchain, real-time)
  │
  ├── User clicks "Back This Research"
  │
  ├── Frontend builds Solana transaction:
  │     - Transfer USDC from backer to escrow PDA
  │     - Mint research tokens to backer wallet
  │     - Write contribution record to ContributionState PDA
  │
  ├── User signs transaction in wallet
  │
  ├── Transaction submitted to Solana via Helius RPC
  │
  └── Helius webhook fires on confirmation:
        - Supabase off-chain index updated
        - Frontend re-renders campaign funding progress
```

***

## Indexing

PepFund uses Helius webhooks to listen for confirmed transactions involving the PepFund program. On each event, a serverless function:

1. Parses the transaction accounts and instruction data
2. Derives the updated campaign, contribution, or milestone state
3. Writes the updated state to the Supabase off-chain index

This allows the frontend to serve fast reads from Supabase while ensuring the displayed state reflects confirmed onchain activity within seconds of block confirmation.

***

## Identity and Authentication

PepFund uses **wallet-based authentication**. There are no passwords. A user's Solana wallet address is their identity. Sessions are established by signing a challenge message with the wallet; the signature is verified server-side.

For researchers, wallet authentication is supplemented by ORCID OAuth:

1. Researcher connects wallet (establishes session)
2. Researcher initiates ORCID OAuth flow
3. ORCID returns a verified identifier
4. PepFund links the ORCID iD to the wallet address in Supabase
5. The link is recorded onchain in the campaign's metadata at creation

This means a researcher's ORCID verification is visible to anyone inspecting the campaign's onchain metadata.

***

## Environments

| Environment | Solana Cluster | Notes                                                           |
| ----------- | -------------- | --------------------------------------------------------------- |
| Development | Devnet         | Free SOL/USDC via faucets; no real value                        |
| Staging     | Devnet         | Mirrors production infrastructure; used for pre-release testing |
| Production  | Mainnet        | Live campaigns with real USDC                                   |

Beta access during the current period operates on **Mainnet** with real USDC. Devnet access is available to developers building integrations.


---

# Agent Instructions: 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:

```
GET https://docs.pepfund.xyz/technical-reference/architecture.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.