Frontend Architecture

This document provides a deep technical dive into the StyxPay frontend architecture, implementation details, and design decisions.

Tech Stack Details

Core Framework: Next.js 15

Why Next.js?

• Server-side rendering (SSR) for better SEO

• Automatic code splitting and optimization

• File-based routing system

• Built-in Image and Font optimization

• API routes for backend functionality

• Excellent developer experience

App Router vs Pages Router We use the App Router (introduced in Next.js 13+) for:

• React Server Components by default

• Improved data fetching patterns

• Nested layouts support

• Better performance characteristics

Styling: Tailwind CSS

Configuration (tailwind.config.ts):

{
  content: [
    "./app/**/*.{js,ts,jsx,tsx}",
    "./components/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {
      fontFamily: {
        display: ['var(--font-space-grotesk)'],
        sans: ['var(--font-inter)']
      },
      animation: {
        float: 'float 3s ease-in-out infinite'
      }
    }
  }
}

Custom Utilities:

• .glass-card - Glassmorphism effect

• .text-gradient - Gradient text

• .float - Floating animation

• .shooting-star - Shooting star animation

TypeScript

Configuration (tsconfig.json):

• Strict mode enabled

• Path aliases configured

• Modern ES target

• JSX preservation for Next.js

Benefits:

• Type safety across the codebase

• Better IDE autocomplete

• Catch errors at compile time

• Self-documenting code

Routing Architecture

File-Based Routing

app/
├── page.tsx              → /
├── demo/
│   └── page.tsx          → /demo
├── sign-in/
│   └── page.tsx          → /sign-in
└── sign-up/
    └── page.tsx          → /sign-up

Layout System

Root Layout (app/layout.tsx):

• Applies to all pages

• Contains HTML structure

• Loads global fonts

• Includes metadata

Custom Layouts:

• app/demo/layout.tsx - Overrides root layout to remove nav/footer

Layout Hierarchy:

RootLayout (fonts, metadata)
  → Homepage (with Navbar & Footer)
  → DemoLayout (no Navbar/Footer)
    → Demo Dashboard

Component Architecture

Component Types

1. Page Components (page.tsx)

   • Default exports

   • Can be Server or Client Components

   • Define route content

2. Layout Components (layout.tsx)

   • Wrap page content

   • Shared UI elements

   • Preserve state across navigations

3. Shared Components (app/components/)

   • Navbar, Footer

   • Reusable across pages

Server vs Client Components

Server Components (default):

• No JavaScript sent to client

• Can access backend directly

• Better performance

• Used for: Layouts, static content

Client Components ('use client'):

• Interactive elements

• React hooks (useState, useEffect)

• Browser APIs

• Used for: Demo dashboard, interactive forms

Example:

'use client' // Directive for client component

import { useState } from 'react'

export default function DemoPage() {
  const [activeTab, setActiveTab] = useState('overview')
  // ... interactive logic
}

Styling Implementation

Global Styles (globals.css)

Structure:

1. Tailwind directives

2. CSS variables (theme)

3. Base styles (body, scrollbar)

4. Utility classes

5. Animations

CSS Variables:

:root {
  --radius: 0.5rem;
  --background: 10 10 20;
  --foreground: 255 255 255;
  --primary: 99 102 241;
  /* ... more theme variables */
}

Benefits:

• Consistent theming

• Easy theme switching

• Tailwind integration

Animation System

Shooting Stars:

@keyframes shooting-star-animation {
  0% {
    transform: translateX(0) translateY(0) rotate(45deg);
    opacity: 1;
    width: 0;
  }
  20% {
    width: 200px;
    opacity: 1;
  }
  100% {
    transform: translateX(600px) translateY(600px) rotate(45deg);
    opacity: 0;
    width: 0;
  }
}

Floating:

@keyframes float {
  0%, 100% { transform: translateY(0px); }
  50% { transform: translateY(-10px); }
}

.float {
  animation: float 3s ease-in-out infinite;
}

State Management

Current Approach: React useState

For the demo dashboard:

const [activeTab, setActiveTab] = useState('overview')

Why no global state library?

• Simple application state

• No complex data flows

• Local component state sufficient

• Reduces bundle size

Future Considerations

As the app grows, consider:

• Zustand - Lightweight state management

• React Context - Shared state without prop drilling

• TanStack Query - Server state management

• Jotai - Atomic state management

Data Fetching

Current: Static Demo Data

Demo dashboard uses hardcoded data:

const transactions = [
  { name: 'Coinbase', amount: '+$4,200.00', ... },
  { name: 'AWS', amount: '-$240.50', ... },
  // ...
]

Future: API Integration

Planned architecture:

1. API Routes (app/api/)

   • Next.js server-side endpoints

   • Authentication middleware

   • Database connections

2. Data Fetching Patterns

   // Server Component
   async function getData() {
     const res = await fetch('https://api.styxpay.app/transactions')
     return res.json()
   }
   
   export default async function Page() {
     const data = await getData()
     return <div>{/* render data */}</div>
   }

3. Client-Side Fetching

   'use client'
   import useSWR from 'swr'
   
   export default function Dashboard() {
     const { data } = useSWR('/api/transactions', fetcher)
     // ...
   }

Image Optimization

Using Next.js <Image> component:

import Image from 'next/image'

<Image
  src="/logo.png"
  alt="StyxPay Logo"
  width={32}
  height={32}
  className="w-8 h-8"
/>

Benefits:

• Automatic WebP conversion

• Responsive image sizing

• Lazy loading

• Blur placeholder support

• Prevents layout shift

Font Loading Strategy

next/font Integration

import { Inter, Space_Grotesk } from 'next/font/google'

const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
  weight: ['300', '400', '500', '600'],
})

const spaceGrotesk = Space_Grotesk({
  subsets: ['latin'],
  variable: '--font-space-grotesk',
  weight: ['300', '400', '500', '600'],
})

Benefits:

• Self-hosted fonts (no external requests)

• Automatic font subsetting

• Zero layout shift

• Better performance

Performance Optimizations

1. Code Splitting

Automatic per-route splitting:

• Each page is a separate bundle

• Shared dependencies in common chunk

• Dynamic imports for heavy components

2. Bundle Analysis

Check bundle size:

npm run build
# Analyze output in .next/analyze

3. Image Optimization

• Serve WebP/AVIF formats

• Responsive images

• Lazy loading below fold

4. CSS Optimization

• Tailwind purges unused styles

• Critical CSS inlined

• CSS modules for component styles

5. Rendering Strategy

• Static pages: Pre-rendered at build time

• Dynamic pages: Server-side rendering

• Interactive parts: Client-side hydration

Security Considerations

1. XSS Protection

• React escapes content by default

• Avoid dangerouslySetInnerHTML

• Sanitize user input

2. CSRF Protection

• SameSite cookies

• CSRF tokens for forms

• Verify origin headers

3. Content Security Policy

// next.config.ts
{
  headers: [
    {
      source: '/:path*',
      headers: [
        {
          key: 'Content-Security-Policy',
          value: "default-src 'self'; script-src 'self' 'unsafe-inline';"
        }
      ]
    }
  ]
}

4. Environment Variables

• Never expose secrets in client code

• Use NEXT_PUBLIC_ prefix for public vars

• Validate env vars at build time

Error Handling

Error Boundaries

// app/error.tsx
'use client'

export default function Error({
  error,
  reset,
}: {
  error: Error
  reset: () => void
}) {
  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  )
}

Not Found Pages

// app/not-found.tsx
export default function NotFound() {
  return <div>Page not found</div>
}

Testing Strategy

Planned Testing Approach

1. Unit Tests - Jest + React Testing Library

   npm test

2. E2E Tests - Playwright

   npm run test:e2e

3. Visual Regression - Percy or Chromatic

4. Type Checking

   npx tsc --noEmit

Build & Deployment

Build Process

npm run build

Steps:

1. TypeScript compilation

2. Bundle JavaScript/CSS

3. Optimize images

4. Generate static pages

5. Create server functions

Output

.next/
├── static/          # Static assets
├── server/          # Server-side code
└── cache/           # Build cache

Environment Variables

.env.local (development):

NEXT_PUBLIC_APP_URL=http://localhost:3000
NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com

.env.production (production):

NEXT_PUBLIC_APP_URL=https://styxpay.app
NEXT_PUBLIC_SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

Monitoring & Analytics

Planned Integrations

1. Vercel Analytics

   • Web Vitals tracking

   • Performance monitoring

2. Error Tracking

   • Sentry for error reporting

   • Source map upload

3. User Analytics

   • Privacy-focused analytics

   • Event tracking

Accessibility

ARIA Labels

<button aria-label="Open navigation menu">
  <MenuIcon />
</button>

Keyboard Navigation

• Tab order follows visual hierarchy

• Focus indicators visible

• Escape closes modals

Screen Readers

• Semantic HTML

• Alt text for images

• Skip to content links

Related Documentation

• Project Overview

• Components Guide

• Deployment Guide

---

Last Updated: January 2026