Frontend Architecture

Technology Stack

Core Technologies

React 18

Modern UI library with concurrent features and automatic batching

TypeScript 5.3

Type-safe development with strict mode enabled

Vite

Lightning-fast build tool with HMR and optimized production builds

Tailwind CSS

Utility-first CSS framework with custom design system

Dependencies

package.json

{
  "dependencies": {
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "react-router-dom": "^6.20.1",
    "zustand": "^4.4.6",
    "axios": "^1.6.2",
    "@solana/web3.js": "^1.87.6",
    "@solana/wallet-adapter-react": "^0.15.35",
    "lucide-react": "^0.294.0",
    "clsx": "^2.0.0"
  }
}

Project Structure

packages/frontend/
├── src/
│   ├── App.tsx                 # Root component with routing
│   ├── main.tsx                # Entry point
│   │
│   ├── components/             # Reusable UI components
│   │   ├── Header.tsx          # Navigation header
│   │   ├── Footer.tsx          # Site footer
│   │   ├── Layout.tsx          # Page layout wrapper
│   │   ├── IDLUpload.tsx       # IDL file upload component
│   │   ├── InstructionExplorer.tsx  # Instruction browser
│   │   ├── PDAExplorer.tsx     # PDA derivation tool
│   │   ├── ProjectCard.tsx     # Project list item
│   │   └── Toast.tsx           # Notification system
│   │
│   ├── pages/                  # Page components
│   │   ├── Home.tsx            # Landing page
│   │   ├── Dashboard.tsx       # User dashboard
│   │   ├── Explorer.tsx        # Public project explorer
│   │   ├── ProjectDetail.tsx   # Project details view
│   │   ├── AuthCallback.tsx    # OAuth callback handler
│   │   ├── AuthError.tsx       # Auth error page
│   │   └── NotFound.tsx        # 404 page
│   │
│   ├── store/                  # Zustand state management
│   │   ├── auth.ts             # Authentication state
│   │   └── projects.ts         # Projects state
│   │
│   ├── api/                    # API client
│   │   └── client.ts           # Axios instance with interceptors
│   │
│   └── types/                  # TypeScript definitions
│       └── index.ts            # Shared types
│
├── assets/                     # Static assets
│   ├── logo.png
│   └── favicon.ico
│
├── index.html                  # HTML template
├── vite.config.ts              # Vite configuration
├── tailwind.config.js          # Tailwind CSS config
├── tsconfig.json               # TypeScript config
└── package.json

Application Architecture

Routing Setup

The application uses React Router v6 for client-side routing:

App.tsx

import { BrowserRouter as Router, Routes, Route } from 'react-router-dom'
import Layout from '@/components/Layout'
import Home from '@/pages/Home'
import Dashboard from '@/pages/Dashboard'
import Explorer from '@/pages/Explorer'
import ProjectDetail from '@/pages/ProjectDetail'
import AuthCallback from '@/pages/AuthCallback'
import { useAuthStore } from '@/store/auth'

function App(): JSX.Element {
  const initialize = useAuthStore((s) => s.initialize)

  useEffect(() => {
    initialize() // Load user from localStorage on mount
  }, [initialize])

  return (
    <ToastProvider>
      <Router>
        <Routes>
          <Route element={<Layout />}>
            <Route path="/" element={<Home />} />
            <Route path="/dashboard" element={<Dashboard />} />
            <Route path="/explorer" element={<Explorer />} />
            <Route path="/project/:projectId" element={<ProjectDetail />} />
            <Route path="/auth/callback" element={<AuthCallback />} />
            <Route path="*" element={<NotFound />} />
          </Route>
        </Routes>
      </Router>
    </ToastProvider>
  )
}

Layout Component

Shared layout with header and footer:

Layout.tsx

import { Outlet } from 'react-router-dom'
import Header from './Header'
import Footer from './Footer'

export default function Layout() {
  return (
    <div className="min-h-screen flex flex-col bg-dark-900">
      <Header />
      <main className="flex-1">
        <Outlet /> {/* Nested routes render here */}
      </main>
      <Footer />
    </div>
  )
}

State Management with Zustand

Authentication Store

Manages user authentication state:

store/auth.ts

import { create } from 'zustand'
import { fetchCurrentUser } from '../api/client'

interface User {
  id: string
  username: string
  email: string
  avatar_url: string
  projectCount?: number
}

interface AuthState {
  user: User | null
  token: string | null
  isLoading: boolean
  isAuthenticated: boolean

  setToken: (token: string) => void
  setUser: (user: User) => void
  loadUser: () => Promise<void>
  logout: () => void
  initialize: () => Promise<void>
}

export const useAuthStore = create<AuthState>((set, get) => ({
  user: null,
  token: localStorage.getItem('token'),
  isLoading: true,
  isAuthenticated: false,

  setToken: (token: string) => {
    localStorage.setItem('token', token)
    set({ token, isAuthenticated: true })
  },

  setUser: (user: User) => {
    localStorage.setItem('user', JSON.stringify(user))
    set({ user, isAuthenticated: true })
  },

  loadUser: async () => {
    try {
      set({ isLoading: true })
      const user = await fetchCurrentUser()
      set({ user, isAuthenticated: true, isLoading: false })
      localStorage.setItem('user', JSON.stringify(user))
    } catch {
      set({ user: null, isAuthenticated: false, isLoading: false })
      localStorage.removeItem('token')
      localStorage.removeItem('user')
    }
  },

  logout: () => {
    localStorage.removeItem('token')
    localStorage.removeItem('user')
    set({ user: null, token: null, isAuthenticated: false })
  },

  initialize: async () => {
    const token = localStorage.getItem('token')
    if (token) {
      set({ token })
      // Try to load cached user first for instant UI
      const cachedUser = localStorage.getItem('user')
      if (cachedUser) {
        try {
          set({ user: JSON.parse(cachedUser), isAuthenticated: true })
        } catch {}
      }
      // Then refresh from API
      await get().loadUser()
    } else {
      set({ isLoading: false })
    }
  },
}))

Usage in Components:

import { useAuthStore } from '@/store/auth'

function Dashboard() {
  const { user, isAuthenticated, logout } = useAuthStore()

  if (!isAuthenticated) {
    return <Navigate to="/" />
  }

  return (
    <div>
      <h1>Welcome, {user?.username}</h1>
      <button onClick={logout}>Logout</button>
    </div>
  )
}

Projects Store

Manages project list and selection:

store/projects.ts

import { create } from 'zustand'

interface Project {
  id: string
  name: string
  description: string
  program_id: string
  is_public: boolean
  created_at: string
}

interface ProjectsState {
  projects: Project[]
  selectedProject: Project | null
  isLoading: boolean

  setProjects: (projects: Project[]) => void
  selectProject: (project: Project) => void
  addProject: (project: Project) => void
  removeProject: (id: string) => void
}

export const useProjectsStore = create<ProjectsState>((set) => ({
  projects: [],
  selectedProject: null,
  isLoading: false,

  setProjects: (projects) => set({ projects }),
  selectProject: (project) => set({ selectedProject: project }),
  addProject: (project) =>
    set((state) => ({ projects: [...state.projects, project] })),
  removeProject: (id) =>
    set((state) => ({
      projects: state.projects.filter((p) => p.id !== id),
    })),
}))

API Client

Axios instance with authentication interceptors:

api/client.ts

import axios from 'axios'
import { useAuthStore } from '@/store/auth'

const client = axios.create({
  baseURL: import.meta.env.VITE_API_URL || '/api',
  headers: {
    'Content-Type': 'application/json',
  },
})

// Add auth token to requests
client.interceptors.request.use((config) => {
  const token = useAuthStore.getState().token
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

// Handle 401 responses
client.interceptors.response.use(
  (response) => response,
  (error) => {
    if (error.response?.status === 401) {
      useAuthStore.getState().logout()
      window.location.href = '/'
    }
    return Promise.reject(error)
  }
)

export default client

Design System

Tailwind Configuration

Custom design tokens:

tailwind.config.js

export default {
  theme: {
    extend: {
      colors: {
        primary: '#14F195',     // Solana green
        secondary: '#00D9FF',   // Cyan
        accent: '#FF3333',      // Red
        dark: {
          900: '#0a0f0d',       // Background
          850: '#1a2e25',       // Surface
          800: '#2f2f5e',       // Elevated
        },
        surface: {
          DEFAULT: '#0d1411',
          elevated: '#111d18',
          card: '#152219',
        },
      },
      fontFamily: {
        mono: ['JetBrains Mono', 'Fira Code', 'monospace'],
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
      animation: {
        'pulse-primary': 'pulse-primary 2s cubic-bezier(0.4, 0, 0.6, 1) infinite',
        'glow': 'glow 2s ease-in-out infinite alternate',
      },
    },
  },
}

Component Patterns

Button Component:

import clsx from 'clsx'

interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline'
  size?: 'sm' | 'md' | 'lg'
  children: React.ReactNode
  onClick?: () => void
}

export function Button({ variant = 'primary', size = 'md', children, onClick }: ButtonProps) {
  return (
    <button
      onClick={onClick}
      className={clsx(
        'font-medium rounded-lg transition-all',
        {
          'bg-primary text-dark-900 hover:bg-primary/90': variant === 'primary',
          'bg-secondary text-dark-900 hover:bg-secondary/90': variant === 'secondary',
          'border-2 border-primary text-primary hover:bg-primary/10': variant === 'outline',
        },
        {
          'px-3 py-1.5 text-sm': size === 'sm',
          'px-4 py-2 text-base': size === 'md',
          'px-6 py-3 text-lg': size === 'lg',
        }
      )}
    >
      {children}
    </button>
  )
}

Build Configuration

Vite Setup

vite.config.ts

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import path from 'path'

export default defineConfig({
  plugins: [react()],
  publicDir: 'assets',
  resolve: {
    alias: {
      '@shared': path.resolve(__dirname, '../shared/src'),
      '@': path.resolve(__dirname, './src'),
    },
  },
  server: {
    port: 5173,
    proxy: {
      '/api': {
        target: 'http://api.orquestra.dev',
        changeOrigin: true,
      },
      '/auth/github': {
        target: 'http://api.orquestra.dev',
        changeOrigin: true,
      },
    },
  },
  build: {
    outDir: 'dist',
    sourcemap: false,
    minify: 'terser',
    chunkSizeWarningLimit: 1000,
  },
})

Performance Optimizations

Code Splitting

import { lazy, Suspense } from 'react'

const ProjectDetail = lazy(() => import('@/pages/ProjectDetail'))

function App() {
  return (
    <Suspense fallback={<LoadingSpinner />}>
      <Routes>
        <Route path="/project/:id" element={<ProjectDetail />} />
      </Routes>
    </Suspense>
  )
}

Image Optimization

Use Cloudflare Image Resizing for avatars
Lazy load images below the fold
WebP format with PNG fallback

Bundle Optimization

# Production build stats
Chunk Size Limit: 1000 KB
Gzip Compression: Enabled
Tree Shaking:     Enabled
Minification:     Terser

Development Workflow

Local Development

# Start dev server with HMR
bun run dev:frontend

# Build for production
bun run build

# Preview production build
bun run preview

# Type checking
bun run type-check

# Linting
bun run lint:fix

Environment Variables

.env.local

VITE_API_URL=http://localhost:8787
VITE_FRONTEND_URL=http://localhost:5173

Testing Strategy

Unit Tests (Planned)

import { render, screen } from '@testing-library/react'
import { Button } from '@/components/Button'

test('renders button with text', () => {
  render(<Button>Click me</Button>)
  expect(screen.getByText('Click me')).toBeInTheDocument()
})

E2E Tests (Planned)

Cypress or Playwright for user flows
Test authentication flow
Test IDL upload and project creation
Test transaction building

Backend Architecture

Hono API, services, and middleware

System Architecture

High-level system design and data flow

Component Library

Reusable UI components

API Reference

API endpoints and schemas

Setup

Architecture

Contributing

Frontend Architecture

Technology Stack

Core Technologies

React 18

TypeScript 5.3

Vite

Tailwind CSS

Dependencies

Project Structure

Application Architecture

Routing Setup

Layout Component

State Management with Zustand

Authentication Store

Projects Store

API Client

Design System

Tailwind Configuration

Component Patterns

Build Configuration

Vite Setup

Performance Optimizations

Code Splitting

Image Optimization

Bundle Optimization

Development Workflow

Local Development

Environment Variables

Testing Strategy

Unit Tests (Planned)

E2E Tests (Planned)

Backend Architecture

System Architecture

Component Library

API Reference

Build docs developers (and LLMs) love

Setup

Architecture

Contributing

Documentation Index

​Technology Stack

​Core Technologies

React 18

TypeScript 5.3

Vite

Tailwind CSS

​Dependencies

​Project Structure

​Application Architecture

​Routing Setup

​Layout Component

​State Management with Zustand

​Authentication Store

​Projects Store

​API Client

​Design System

​Tailwind Configuration

​Component Patterns

​Build Configuration

​Vite Setup

​Performance Optimizations

​Code Splitting

​Image Optimization

​Bundle Optimization

​Development Workflow

​Local Development

​Environment Variables

​Testing Strategy

​Unit Tests (Planned)

​E2E Tests (Planned)

​Related Documentation

Backend Architecture

System Architecture

Component Library

API Reference

Build docs developers (and LLMs) love

Technology Stack

Core Technologies

Dependencies

Project Structure

Application Architecture

Routing Setup

Layout Component

State Management with Zustand

Authentication Store

Projects Store

API Client

Design System

Tailwind Configuration

Component Patterns

Build Configuration

Vite Setup

Performance Optimizations

Code Splitting

Image Optimization

Bundle Optimization

Development Workflow

Local Development

Environment Variables

Testing Strategy

Unit Tests (Planned)

E2E Tests (Planned)

Related Documentation