Full-Stack SocketFi App: Reference Architecture Guide

This page describes SocketPay, a reference application that demonstrates every major SocketFi capability working together end-to-end. Rather than listing every line of code, it explains the architecture — how the layers connect, what each module does, and which patterns you should replicate in your own production application. By the time you finish reading this page, you’ll understand the recommended full-stack SocketFi structure and be ready to adapt it to your own product.

What SocketPay covers

Authentication

Passkey-powered sign-in that creates or loads a smart wallet on first use.

Wallet dashboard

Real-time balance reads and asset display using readContract().

Token transfers

Full transfer form with status lifecycle, approval flow, and post-tx refresh.

Backend verification

Express API with verifyAuth() middleware protecting every sensitive route.

Activity feed

Transaction history stored server-side and displayed in the frontend.

Security center

Credential rotation and account recovery entry points in a settings page.

High-level architecture

┌─────────────────────────────────────┐
│           React Frontend            │
│  Auth → Dashboard → Transactions    │
│  @socketfi/react                    │
└────────────────┬────────────────────┘
                 │  HTTPS API calls
                 │  Authorization: Bearer <token>
                 ▼
┌─────────────────────────────────────┐
│          Express Backend            │
│  authMiddleware → verifyAuth()      │
│  @socketfi/server                   │
└────────────────┬────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│        SocketFi Services            │
│  Smart Wallet · Passkey Auth        │
└────────────────┬────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────┐
│     Soroban / Stellar Network       │
│  Smart contracts · On-chain state   │
└─────────────────────────────────────┘

Repository structure

socketpay/
├── apps/
│   └── web/                        # React frontend (Vite + TypeScript)
│       └── src/
│           ├── socketfi/
│           │   └── client.ts       # SDK singleton
│           ├── auth/
│           │   ├── AuthContext.tsx
│           │   ├── AuthProvider.tsx
│           │   └── useAuth.ts
│           ├── wallet/
│           │   ├── useBalance.ts   # readContract() hook
│           │   └── WalletCard.tsx
│           ├── transactions/
│           │   ├── transactionService.ts
│           │   ├── TransferForm.tsx
│           │   └── TransactionHistory.tsx
│           ├── settings/
│           │   └── SecurityPage.tsx
│           ├── pages/
│           │   ├── LoginPage.tsx
│           │   ├── DashboardPage.tsx
│           │   └── SettingsPage.tsx
│           └── App.tsx
│
└── server/                         # Express backend (Node.js + TypeScript)
    └── src/
        ├── middleware/
        │   └── auth.ts             # verifyAuth() middleware
        ├── routes/
        │   ├── profile.ts
        │   ├── wallet.ts
        │   └── activity.ts
        ├── services/
        │   └── activityService.ts  # Persist & query tx history
        └── app.ts

Environment variables

# apps/web/.env
VITE_SOCKETFI_CLIENT_ID=your_client_id
VITE_TOKEN_CONTRACT_ID=your_token_contract
VITE_API_BASE_URL=https://api.socketpay.app

# server/.env
DATABASE_URL=postgres://...
PORT=3000

Authentication flow

SDK initialization is the first thing that runs. The AuthProvider wraps the entire application and restores any persisted session before rendering routes.

apps/web/src/socketfi/client.ts

import { SocketFi } from "@socketfi/react";

export const socketfi = new SocketFi({
  clientId: import.meta.env.VITE_SOCKETFI_CLIENT_ID,
  network: "MAINNET",
});

User lands on /login
       ↓
AuthProvider mounts → reads localStorage for existing session
       ↓  (no session)
LoginPage renders "Continue with passkey" button
       ↓
socketfi.authenticate() → hosted passkey flow
       ↓
{ socketfiAccessToken, userProfile: { id, wallet } } returned
       ↓
Session stored in localStorage → setSession(result)
       ↓
ProtectedRoute passes → user lands on /dashboard

See React Authentication for the complete file-by-file implementation.

Wallet dashboard

The dashboard reads balances directly from Soroban using readContract() and caches them with React Query. After any transaction, the query is invalidated so the display stays accurate.

apps/web/src/wallet/useBalance.ts

import { useQuery } from "@tanstack/react-query";
import { socketfi } from "../socketfi/client";

export function useBalance(walletAddress: string, contractId: string) {
  return useQuery({
    queryKey: ["balance", walletAddress, contractId],
    queryFn: async () => {
      const result = await socketfi.readContract({
        contractId,
        method: "balance",
        args: [walletAddress],
      });
      return result as string;
    },
    enabled: !!walletAddress,
    staleTime: 30_000, // 30 seconds
  });
}

Dashboard mounts
       ↓
useBalance() → socketfi.readContract({ method: "balance", args: [wallet] })
       ↓
Soroban simulation runs (no user approval needed for reads)
       ↓
Balance displayed
       ↓  (after a transfer)
queryClient.invalidateQueries(["balance", wallet])  →  fresh fetch

Transaction flow

Every state-changing operation goes through requestTransaction(). SocketPay wraps it in a service layer, leaving TransferForm free of SDK-specific logic.

apps/web/src/transactions/transactionService.ts

import { socketfi } from "../socketfi/client";

export async function sendTokens(
  contractId: string,
  from: string,
  to: string,
  amount: string
) {
  return socketfi.requestTransaction({
    contractId,
    method: "transfer",
    args: [from, to, amount],
  });
}

User fills TransferForm and clicks Send
       ↓
Client-side validation (address format, positive amount)
       ↓
transactionService.sendTokens() called
       ↓
Hosted approval screen launches
       ↓
User approves with passkey
       ↓
{ success: true, transactionHash: "abc123…" }
       ↓
queryClient.invalidateQueries(["balance"])  →  balance refreshed
Server receives POST /api/activity with hash → stored in DB
       ↓
ActivityFeed re-fetches and shows the new entry

See React Transactions for the complete form and status-lifecycle implementation.

Backend verification

The Express backend protects all /api routes with authMiddleware. No route handler ever trusts user-supplied identity.

server/src/middleware/auth.ts

import { verifyAuth } from "@socketfi/server";
import type { Request, Response, NextFunction } from "express";

export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ message: "Unauthorized." });

  const result = await verifyAuth(token);
  if (!result.valid) return res.status(401).json({ message: "Unauthorized." });

  req.user = { id: result.user.id, wallet: result.wallet };
  next();
}

server/src/app.ts

import express from "express";
import { authMiddleware } from "./middleware/auth";
import profileRoutes from "./routes/profile";
import walletRoutes from "./routes/wallet";
import activityRoutes from "./routes/activity";

const app = express();
app.use(express.json());

app.get("/health", (_req, res) => res.json({ ok: true }));

app.use("/api", authMiddleware, profileRoutes);
app.use("/api", authMiddleware, walletRoutes);
app.use("/api", authMiddleware, activityRoutes);

export default app;

See Server Verification for the full middleware, route, and TypeScript type-extension implementation.

Activity feed

SocketPay stores transaction hashes server-side after every successful transfer. The frontend fetches them with React Query.

// Activity record shape
interface ActivityRecord {
  hash: string;
  type: "transfer" | "deposit" | "withdrawal" | "vote" | "stake";
  status: "pending" | "confirmed" | "failed";
  timestamp: string;
  wallet: string;
}

server/src/routes/activity.ts

import { Router } from "express";

const router = Router();

router.get("/activity", async (req, res) => {
  const activities = await activityService.getByWallet(req.user!.wallet);
  res.json(activities);
});

router.post("/activity", async (req, res) => {
  const { hash, type } = req.body as { hash: string; type: string };
  await activityService.create({ wallet: req.user!.wallet, hash, type });
  res.status(201).json({ created: true });
});

export default router;

Security center

Give users a dedicated settings page to manage their passkey credentials and initiate account recovery if needed.

Security Settings
├── Registered passkeys (list + remove)
├── Credential rotation  →  generate new passkey, authorize change
└── Account recovery     →  entry point if device is lost

apps/web/src/settings/SecurityPage.tsx

import { useAuth } from "../auth/useAuth";

export default function SecurityPage() {
  const { session, logout } = useAuth();

  return (
    <main>
      <h1>Security</h1>
      <section>
        <h2>Your wallet</h2>
        <code>{session?.userProfile?.wallet}</code>
      </section>
      <section>
        <h2>Credential rotation</h2>
        <p>Register a new passkey to replace your current one.</p>
        {/* Link to credential rotation flow */}
      </section>
      <section>
        <h2>Account recovery</h2>
        <p>Restore access if you lose your device.</p>
        {/* Link to recovery flow */}
      </section>
      <button onClick={logout}>Sign out</button>
    </main>
  );
}

React Query setup

Wrap your app with QueryClientProvider at the root alongside AuthProvider:

apps/web/src/main.tsx

import React from "react";
import ReactDOM from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { AuthProvider } from "./auth/AuthProvider";
import App from "./App";

const queryClient = new QueryClient({
  defaultOptions: {
    queries: { staleTime: 30_000, retry: 2 },
  },
});

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <QueryClientProvider client={queryClient}>
      <AuthProvider>
        <App />
      </AuthProvider>
    </QueryClientProvider>
  </React.StrictMode>
);

Recommended production stack

Layer	Technology
Frontend framework	React 18+ with TypeScript
Bundler	Vite or Next.js 14+
Data fetching	TanStack Query (React Query)
Frontend SDK	`@socketfi/react`
Backend runtime	Node.js 20+
Backend framework	Express or Fastify
Backend SDK	`@socketfi/server`
Database	PostgreSQL (activity, user metadata)
Hosting	Any cloud provider with HTTPS support
Observability	Error tracking + APM (e.g., Sentry, Datadog)

Production checklist

✓ HTTPS enabled on all domains
✓ Environment variables set correctly (TESTNET → MAINNET)
✓ authMiddleware applied to every protected API route
✓ verifyAuth() called — never trust client-supplied wallet addresses
✓ Sessions stored securely (localStorage on web, SecureStore on mobile)
✓ Transaction hashes persisted server-side for history and support
✓ Balance queries invalidated after every confirmed transaction
✓ Error boundaries wrapping major UI sections
✓ USER_CANCELLED handled gracefully (not treated as an app error)
✓ Credential rotation and recovery entry points available to users
✓ Monitoring and alerting enabled for auth failures and tx errors

Full user lifecycle

User arrives at socketpay.app
       ↓
Passkey authentication (sign-up or sign-in)
       ↓
Smart wallet created or loaded
       ↓
Dashboard: balance read from Soroban
       ↓
User initiates a transfer
       ↓
Hosted approval screen — user signs with passkey
       ↓
Transaction confirmed — transactionHash stored server-side
       ↓
Balance refreshed — activity feed updated
       ↓
User visits Security settings
       ↓
Optional: rotate credential or initiate recovery

Integration Guides

Recovery & Rotation

Examples

Resources

Full-Stack SocketFi App: Reference Architecture Guide

What SocketPay covers

Authentication

Wallet dashboard

Token transfers

Backend verification

Activity feed

Security center

High-level architecture

Repository structure

Environment variables

Authentication flow

Wallet dashboard

Transaction flow

Backend verification

Activity feed

Security center

React Query setup

Recommended production stack

Production checklist

Full user lifecycle

​What SocketPay covers

Authentication

Wallet dashboard

Token transfers

Backend verification

Activity feed

Security center

​High-level architecture

​Repository structure

​Environment variables

​Authentication flow

​Wallet dashboard

​Transaction flow

​Backend verification

​Activity feed

​Security center

​React Query setup

​Recommended production stack

​Production checklist

​Full user lifecycle

What SocketPay covers

High-level architecture

Repository structure

Environment variables

Authentication flow

Wallet dashboard

Transaction flow

Backend verification

Activity feed

Security center

React Query setup

Recommended production stack

Production checklist

Full user lifecycle