System architecture

#One application, several trust boundaries

Aero is a single Next.js application that serves marketing, a Fuji wallet sandbox and a small identity API. The contracts live on Avalanche Fuji. The documentation site is a separate static application deployed at https://docs.useaero.org.

The important architectural fact is that the browser talks to contracts through the user's wallet. There is no Aero transaction-signing service, no custodial key and no server-side transfer authorization. The identity API adds accounts and sessions, but those sessions never authorize a token transfer.

#High-level architecture

flowchart TD
  subgraph Device["User device"]
    UI["Aero web app<br/>marketing · sandbox"]
    Wallet["External wallet<br/>Reown AppKit / Wagmi"]
    Local["Browser storage<br/>activity · contacts"]
  end

  subgraph Runtime["Aero Next.js runtime"]
    Pages["Pages and API routes"]
    Gate["Release gates"]
    Identity["Identity API<br/>challenge · session"]
    Waitlist["Waitlist / admin API"]
  end

  subgraph Stores["Server-side stores"]
    DB[("Neon Postgres")]
    Email["Resend"]
  end

  subgraph Fuji["Avalanche Fuji · 43113"]
    Contracts["Aero contracts<br/>Names · Pay · Bank<br/>Vault · Router"]
    Token["TestUSDC (tUSDC)<br/>no cash value"]
    Markets["Mock markets<br/>synthetic yield"]
  end

  UI --> Pages
  UI --> Local
  UI --> Wallet
  UI -->|reads| Contracts
  Wallet -->|signed writes| Contracts
  Pages --> Gate
  Pages --> Identity
  Pages --> Waitlist
  Identity --> DB
  Waitlist --> DB
  Waitlist --> Email
  Contracts --> Token
  Contracts --> Markets
  UI -.->|documentation link| Docs["docs.useaero.org<br/>static site"]

The diagram shows code paths, not production integrations. The markets behind the adapters are mock contracts in the supplied deployment. The identity database is implemented in source and migrations but has not been applied to Neon in the recorded milestone.

#Components

#Marketing and waitlist

app/page.tsx renders the public landing page. The waitlist API accepts an email and preferred username, sends a confirmation through Resend, and stores the record in Neon when DATABASE_URL exists, otherwise in a local JSONL file. The waitlist is not an account and does not reserve an on-chain handle.

#Fuji sandbox

/testnet is the wallet-connected application. Middleware rewrites requests on testnet.useaero.org to the /testnet route. The sandbox reads Fuji through a public RPC, asks the connected wallet to sign writes, and stores presentation state such as recent activity, contacts and seen notices in browser storage.

#Identity API

The identity API is under app/api/identity/. It implements Fuji EOA SIWE challenges, verification, server-side sessions, wallet linking, reauthentication, primary switching and revocation. It uses a dedicated runtime database URL and a least-privilege database role. Account creation is closed.

#Contracts

The contract set separates concerns:

#Request and data flow

A Send transaction follows this path:

1. The browser reads the recipient handle from AeroNames, or validates a raw address.
2. The user signs an approval and then a payment transaction in the wallet.
3. The wallet submits to Fuji. Aero does not see or hold the private key.
4. AeroPay calls transferFrom, emits Paid with a memo and timestamp, or the token's transfer is called directly.
5. Wagmi waits for a receipt. The browser shows the hash and may write a local activity entry.
6. The durable evidence is the Fuji transaction and contract event. There is no internal ledger or reconciliation service.

An identity request is different: it goes to the Aero server, is rate-limited and origin-checked, and uses the identity database. It proves wallet ownership for account purposes. It does not sign or submit a transfer.

#Deployment shape

flowchart TD
  Marketing["useaero.org<br/>marketing + waitlist"] --> App["Next.js deployment"]
  Testnet["testnet.useaero.org<br/>host rewrite to /testnet"] --> App
  App --> Identity["Identity API + Postgres"]
  Wallet["User wallet"] --> Fuji["Avalanche Fuji"]
  Docs["docs.useaero.org<br/>static docs build"] -.->|links| Marketing
  Docs -.->|links| Testnet

The docs domain is intentionally independent. It can be built and deployed without rebuilding the main Next.js app, and a docs outage does not take down the sandbox. DNS and hosting changes are deployment operations outside this repository; see Deployment and operations.

#Trust boundaries

The Security and engineering page expands the threat model. Identity and accounts explains why a wallet connection is not authentication.