Frontend architecture

services/web/
  app/                      # Next.js App Router pages
    layout.tsx              # Root layout with providers
    page.tsx                # Landing page
    send/
      page.tsx              # Main app: compare routes & execute
  components/               # React components
    ui/                     # shadcn/ui primitives
    pop-header.tsx          # App header
    remittance-form.tsx     # Search form
    route-card.tsx          # Route comparison card
    transaction-execution.tsx
    proof-of-payment.tsx
  lib/                      # Frontend utilities
    api.ts                  # API base URL configuration
    anchors-api.ts          # Backend API client
    types.ts                # Shared TypeScript types
    wallet-context.tsx      # Stellar wallet provider
  hooks/                    # React hooks
    use-toast.ts
  public/                   # Static assets
    isotipo.png

type AppStep = "search" | "routes" | "execute" | "proof";

<RemittanceForm
  countries={countries}
  onSearch={handleSearch}
  loading={loading}
/>

{sortedRoutes.map((route) => (
  <RouteCard
    key={route.id}
    route={route}
    onSelect={handleSelectRoute}
    selectable={route.available && isMoneyGramRoute}
  />
))}

<TransactionExecution
  route={selectedRoute}
  amount={amount}
  onBack={handleBackToRoutes}
  onComplete={handleTransactionComplete}
/>

<ProofOfPaymentView
  transaction={transaction}
  onNewTransfer={handleNewTransfer}
/>

SendPage (client component)
  └─ WalletProvider
      ├─ PopHeader
      ├─ GradientMesh (background)
      └─ [Current Step]
          ├─ RemittanceForm
          ├─ RouteCard (multiple)
          ├─ TransactionExecution
          └─ ProofOfPaymentView

interface RemittanceFormProps {
  countries: AnchorCountry[];
  onSearch: (origin: string, destination: string, amount: number) => void;
  loading: boolean;
}

interface RouteCardProps {
  route: RemittanceRoute;
  onSelect: (route: RemittanceRoute) => void;
  selectable: boolean;
  selectionHint?: string;
  index: number;
}

const steps = [
  "Authenticating with anchor",      // SEP-10
  "Initiating deposit flow",         // SEP-24
  "Submitting to Stellar",           // Transaction
  "Confirming with destination",     // SEP-24 callback
  "Verifying on-chain",              // Horizon query
];

<div className="proof-container">
  <CheckCircle className="success-icon" />
  <h1>Transfer complete</h1>
  <p>Transaction hash: {transaction.stellarTxHash}</p>
  <a href={stellarExpertUrl} target="_blank">View on StellarExpert</a>
</div>

import { apiUrl } from "./api";

export async function fetchAnchorCountries(): Promise<AnchorCountry[]> {
  const response = await fetch(apiUrl("/api/anchors/countries"));
  if (!response.ok) throw new Error("Failed to fetch countries");
  return response.json();
}

export async function compareRoutes(input: {
  origin: string;
  destination: string;
  amount: number;
}): Promise<{ routes: RemittanceRoute[]; noRouteReason?: string }> {
  const response = await fetch(apiUrl("/api/compare-routes"), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(input),
  });
  if (!response.ok) throw new Error("Failed to compare routes");
  return response.json();
}

# services/web/.env.local
NEXT_PUBLIC_API_BASE_URL=http://localhost:3001

NEXT_PUBLIC_API_BASE_URL=https://api.payonproof.com

const [step, setStep] = useState<AppStep>("search");
const [routes, setRoutes] = useState<RemittanceRoute[]>([]);
const [selectedRoute, setSelectedRoute] = useState<RemittanceRoute | null>(null);
const [transaction, setTransaction] = useState<Transaction | null>(null);

// lib/wallet-context.tsx
export function WalletProvider({ children }: { children: React.ReactNode }) {
  const [publicKey, setPublicKey] = useState<string | null>(null);
  const [isConnected, setIsConnected] = useState(false);

  const connect = async () => {
    if (await isConnected()) {
      const key = await getPublicKey();
      setPublicKey(key);
      setIsConnected(true);
    }
  };

  return (
    <WalletContext.Provider value={{ publicKey, isConnected, connect }}>
      {children}
    </WalletContext.Provider>
  );
}

const { publicKey, connect } = useWallet();

<Button
  variant="outline"
  size="sm"
  className="rounded-xl bg-transparent hover:bg-primary/10"
>
  Select route
</Button>

import { ThemeProvider } from "next-themes";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

import Image from "next/image";

<Image
  src="/isotipo.png"
  alt="POP"
  width={72}
  height={72}
  priority  // Load immediately for hero image
/>

import { Inter } from "next/font/google";

const inter = Inter({ subsets: ["latin"] });

// lib/types.ts
export interface RemittanceRoute {
  id: string;
  originAnchor: {
    id: string;
    name: string;
    country: string;
    currency: string;
    type: "on-ramp";
  };
  destinationAnchor: {
    id: string;
    name: string;
    country: string;
    currency: string;
    type: "off-ramp";
  };
  feePercentage: number;
  feeAmount: number;
  estimatedTime: string;
  exchangeRate: number;
  receivedAmount: number;
  available: boolean;
  recommended: boolean;
}

try {
  const payload = await compareRoutes({ origin, destination, amount });
  setRoutes(payload.routes ?? []);
  setNoRouteReason(payload.noRouteReason ?? null);
  setStep("routes");
} catch (error) {
  const message = error instanceof Error ? error.message : "Failed to fetch routes";
  setRoutes([]);
  setSearchError(message);
} finally {
  setLoading(false);
}

{searchError && (
  <p className="mt-2 text-xs text-destructive">{searchError}</p>
)}

cd services/web
npm install
npm run dev

cp .env.example .env.local
# Edit NEXT_PUBLIC_API_BASE_URL to point to backend