25 KiB
Architecture Guide
Overview
XPack WebUI is built with modern web technologies and follows best practices for scalability, maintainability, and performance. This guide provides an in-depth look at the application's architecture.
Technology Stack
Core Framework
- Next.js 15: React framework with App Router
- React 18: UI library with concurrent features
- TypeScript 5: Type-safe JavaScript
UI & Styling
- NextUI v2: Modern React UI library
- Tailwind CSS: Utility-first CSS framework
- Framer Motion: Animation library
- Lucide React: Icon library
- React Icons: Additional icon sets
State Management
- Zustand: Lightweight state management
- SWR: Data fetching and caching
- React Hook Form: Form state management
- Zod: Schema validation
Internationalization
- react-i18next: Internationalization framework
- i18next: Core i18n functionality
- i18next-browser-languagedetector: Language detection
- i18next-http-backend: Translation loading
Additional Libraries
- Recharts: Charts and analytics visualization
- React Markdown: Markdown content rendering
- Crypto-js: Encryption and security utilities
- Three.js: 3D graphics and effects
- Lottie React: Animation rendering
- Anime.js: Advanced animation library
- React Hot Toast: Toast notifications
- React Hover Video Player: Video interactions
Development Tools
- ESLint: Code linting with Next.js configuration
- TypeScript: Static type checking
- PostCSS: CSS processing
- Autoprefixer: CSS vendor prefixing
Application Architecture
Directory Structure
apps/op/
├── docs/ # Documentation
│ ├── architecture.md # System architecture
│ ├── development.md # Development guide
│ ├── deployment.md # Deployment instructions
│ ├── api.md # API documentation
│ └── troubleshooting.md # Common issues and solutions
├── public/ # Static assets
│ ├── icons/ # Application icons
│ ├── images/ # Images and graphics
│ └── locales/ # Translation files
├── src/ # Source code
│ ├── app/ # Next.js App Router pages
│ │ ├── admin-signin/ # Admin login page
│ │ ├── console/ # Admin console
│ │ ├── dashboard/ # User dashboard
│ │ ├── loginSuccess/ # Login success page
│ │ ├── marketplace/ # Service marketplace
│ │ ├── signin/ # User login page
│ │ ├── system-setting/ # System settings
│ │ ├── wallet/ # Wallet management
│ │ ├── globals.css # Global styles
│ │ ├── layout.tsx # Root layout
│ │ └── page.tsx # Home page
│ ├── components/ # Reusable UI components
│ │ ├── common/ # Common components
│ │ ├── console/ # Console-specific components
│ │ ├── dashboard/ # Dashboard components
│ │ ├── marketplace/ # Marketplace components
│ │ ├── navigation/ # Navigation components
│ │ ├── signin/ # Authentication components
│ │ ├── system-setting/ # Settings components
│ │ ├── ui/ # Base UI components
│ │ └── wallet/ # Wallet components
│ ├── hooks/ # Custom React hooks
│ │ ├── useAuth.ts # Authentication hook
│ │ ├── useLocalStorage.ts # Local storage hook
│ │ └── useTranslation.ts # Translation hook
│ ├── rpc/ # RPC layer
│ │ ├── client.ts # RPC client
│ │ ├── types.ts # RPC types
│ │ └── utils.ts # RPC utilities
│ ├── services/ # API services
│ │ ├── authService.ts # Authentication service
│ │ ├── marketplaceService.ts # Marketplace API
│ │ ├── userService.ts # User management
│ │ └── walletService.ts # Wallet operations
│ ├── shared/ # Shared utilities
│ │ ├── constants/ # Application constants
│ │ ├── lib/ # Utility libraries
│ │ ├── types/ # Shared TypeScript types
│ │ └── utils/ # Helper functions
│ ├── store/ # State management
│ │ ├── authStore.ts # Authentication state
│ │ ├── marketplaceStore.ts # Marketplace state
│ │ ├── userStore.ts # User state
│ │ └── walletStore.ts # Wallet state
│ ├── types/ # TypeScript definitions
│ │ ├── api.ts # API types
│ │ ├── auth.ts # Authentication types
│ │ ├── marketplace.ts # Marketplace types
│ │ └── user.ts # User types
│ └── utils/ # Utility functions
│ ├── api.ts # API utilities
│ ├── auth.ts # Authentication utilities
│ ├── crypto.ts # Cryptographic utilities
│ ├── format.ts # Formatting utilities
│ └── validation.ts # Validation utilities
├── .env.example # Environment variables template
├── .eslintrc.json # ESLint configuration
├── .gitignore # Git ignore rules
├── next.config.ts # Next.js configuration
├── package.json # Dependencies and scripts
├── postcss.config.js # PostCSS configuration
├── tailwind.config.ts # Tailwind CSS configuration
└── tsconfig.json # TypeScript configuration
Architectural Patterns
1. Feature-Based Organization
The application follows a feature-based directory structure where related components, services, and utilities are grouped together:
- Page-Level Features: Each major feature (marketplace, console, dashboard, wallet) has its own directory under
app/ - Component Organization: Components are organized by feature domain (marketplace, console, dashboard, etc.)
- Service Layer: API services are separated by business domain (auth, marketplace, user, wallet)
- State Management: Zustand stores are organized by feature area
src/
├── app/marketplace/ # Marketplace feature
│ ├── [id]/page.tsx # Product detail page
│ └── page.tsx # Marketplace listing
├── components/marketplace/ # Marketplace components
│ ├── ServiceCard.tsx
│ ├── ServiceList.tsx
│ └── SearchFilters.tsx
├── services/ # API services by domain
│ ├── marketplaceService.ts
│ ├── authService.ts
│ └── walletService.ts
├── store/ # State management by feature
│ ├── marketplaceStore.ts
│ ├── authStore.ts
│ └── walletStore.ts
└── rpc/ # RPC layer
├── client.ts
├── types.ts
└── utils.ts
2. Layered Architecture
┌─────────────────────────────────────┐
│ Presentation Layer │
│ (Pages & Components) │
├─────────────────────────────────────┤
│ Business Layer │
│ (Hooks & Stores) │
├─────────────────────────────────────┤
│ Service Layer │
│ (API Services & RPC) │
├─────────────────────────────────────┤
│ Data Layer │
│ (External APIs & Cache) │
└─────────────────────────────────────┘
Layer Responsibilities:
- Presentation Layer: UI components, pages, layouts, and user interactions
- Business Layer: Application logic, state management, and custom hooks
- Service Layer: API integration, RPC communication, and data transformation
- Data Layer: External API calls, caching strategies, and data persistence
3. Security Architecture
- Authentication: JWT-based authentication with secure token storage
- Authorization: Role-based access control (RBAC) for admin and user roles
- Encryption: Client-side encryption using crypto-js for sensitive data
- API Security: Secure API communication with proper error handling
- Input Validation: Zod schema validation for all user inputs
4. Performance Optimization
- Code Splitting: Automatic code splitting with Next.js and lazy loading
- Image Optimization: Next.js Image component for optimized loading
- Caching Strategy: SWR for intelligent data caching and revalidation
- Bundle Optimization: Tree shaking and module optimization
- Virtual Scrolling: For large lists and data sets
5. Component Composition
Components follow a composition pattern for flexibility:
// Base component
function Card({ children, className, ...props }) {
return (
<div className={cn("rounded-lg border", className)} {...props}>
{children}
</div>
)
}
// Composed components
function ServiceCard({ service }) {
return (
<Card className="p-4">
<Card.Header>
<h3>{service.name}</h3>
</Card.Header>
<Card.Content>
<p>{service.description}</p>
</Card.Content>
<Card.Footer>
<Button>Install</Button>
</Card.Footer>
</Card>
)
}
Data Flow
1. Client-Side Data Flow
User Interaction → Component → Hook → Store → Service → API
↓
UI Update ← State Change ← Response
Flow Description:
- User Interaction: User performs an action (click, form submission, etc.)
- Component: React component handles the interaction
- Hook: Custom hook processes the business logic
- Store: Zustand store manages state updates
- Service: API service handles external communication
- API: Backend API processes the request
- Response: Data flows back through the same chain
2. Server-Side Data Flow
Next.js App Router → Server Components → API Routes → External Services
↓
Client Hydration ← SSR ← Data Fetching
Server-Side Features:
- Server Components: React Server Components for initial data loading
- API Routes: Next.js API routes for backend integration
- SSR: Server-side rendering for dynamic content and SEO optimization
- Middleware: Authentication and request processing
3. State Management with Zustand
// Example: Marketplace Store
interface MarketplaceState {
services: Service[]
loading: boolean
error: string | null
fetchServices: () => Promise<void>
selectService: (id: string) => void
}
const useMarketplaceStore = create<MarketplaceState>((set, get) => ({
services: [],
loading: false,
error: null,
fetchServices: async () => {
set({ loading: true, error: null })
try {
const services = await marketplaceService.fetchServices()
set({ services, loading: false })
} catch (error) {
set({ error: error.message, loading: false })
}
},
selectService: (id: string) => {
const service = get().services.find(s => s.id === id)
// Handle service selection logic
}
}))
4. RPC Communication
The application uses a custom RPC layer for backend communication:
// RPC Client Structure
interface RPCClient {
call<T>(method: string, params?: any): Promise<T>
subscribe(event: string, callback: Function): void
unsubscribe(event: string): void
}
// Usage Example
const rpcClient = new RPCClient(config.rpcEndpoint)
// Service method call
const result = await rpcClient.call('marketplace.getServices', {
category: 'ai-tools',
limit: 20
})
// Real-time updates
rpcClient.subscribe('service.updated', (data) => {
// Handle real-time service updates
})
5. Caching Strategy
SWR Configuration:
- Revalidation: Automatic revalidation on focus
- Error Retry: Exponential backoff for failed requests
- Deduplication: Automatic request deduplication
- Optimistic Updates: Immediate UI updates with rollback on error
// SWR Usage Example
const { data, error, mutate } = useSWR(
['services', filters],
() => marketplaceService.fetchServices(filters),
{
revalidateOnFocus: true,
revalidateOnReconnect: true,
errorRetryCount: 3,
dedupingInterval: 5000
}
)
6. Authentication Flow
Login Request → Auth Service → JWT Token → Local Storage
↓
Protected Route → Auth Guard → Token Validation → Access Granted/Denied
Authentication Features:
- JWT Tokens: Secure token-based authentication
- Refresh Tokens: Automatic token refresh
- Role-Based Access: Different access levels for users and admins
- Session Management: Secure session handling with automatic logout
## API Architecture
### 1. Service Layer Pattern
```typescript
// Base API client
class ApiClient {
private baseURL: string
constructor(baseURL: string) {
this.baseURL = baseURL
}
async request<T>(endpoint: string, options?: RequestInit): Promise<T> {
const url = `${this.baseURL}${endpoint}`
const response = await fetch(url, {
headers: {
'Content-Type': 'application/json',
...options?.headers,
},
...options,
})
if (!response.ok) {
throw new Error(`API Error: ${response.status}`)
}
return response.json()
}
}
// Service-specific clients
class ServiceAPI extends ApiClient {
async getServices(): Promise<Service[]> {
return this.request('/services')
}
async getService(id: string): Promise<Service> {
return this.request(`/services/${id}`)
}
async createService(data: CreateServiceRequest): Promise<Service> {
return this.request('/services', {
method: 'POST',
body: JSON.stringify(data),
})
}
}
2. Error Handling Strategy
// Centralized error handling
export class ApiError extends Error {
constructor(
message: string,
public status: number,
public code?: string
) {
super(message)
this.name = 'ApiError'
}
}
// Error boundary for API errors
export function ApiErrorBoundary({ children }) {
return (
<ErrorBoundary
fallback={({ error }) => (
<div className="error-container">
<h2>Something went wrong</h2>
<p>{error.message}</p>
<Button onClick={() => window.location.reload()}>
Retry
</Button>
</div>
)}
>
{children}
</ErrorBoundary>
)
}
Component Architecture
1. Component Hierarchy
App
├── Layout
│ ├── Header
│ │ ├── Navigation
│ │ ├── UserMenu
│ │ └── LanguageSelector
│ ├── Sidebar (conditional)
│ └── Footer
├── Page Components
│ ├── Marketplace
│ │ ├── HeroSection
│ │ ├── SearchFilters
│ │ └── ServiceList
│ │ └── ServiceCard[]
│ ├── Console
│ │ ├── AdminSidebar
│ │ ├── ServiceManagement
│ │ ├── UserManagement
│ │ └── Analytics
│ └── Dashboard
│ ├── UserProfile
│ ├── InstalledServices
│ └── ActivityFeed
└── Shared Components
├── UI Components
├── Form Components
└── Modal Components
2. Component Design Principles
Single Responsibility
Each component has one clear purpose:
// Good: Single responsibility
function ServiceCard({ service }) {
return (
<Card>
<ServiceImage src={service.image} />
<ServiceInfo service={service} />
<ServiceActions service={service} />
</Card>
)
}
// Bad: Multiple responsibilities
function ServiceCardWithModal({ service }) {
const [showModal, setShowModal] = useState(false)
// ... modal logic, card logic, form logic all mixed
}
Composition over Inheritance
Use composition to build complex components:
// Composable modal system
function Modal({ children, isOpen, onClose }) {
return (
<Portal>
<Overlay onClick={onClose} />
<ModalContent>
{children}
</ModalContent>
</Portal>
)
}
function ServiceModal({ service, isOpen, onClose }) {
return (
<Modal isOpen={isOpen} onClose={onClose}>
<Modal.Header>
<h2>{service.name}</h2>
</Modal.Header>
<Modal.Body>
<ServiceDetails service={service} />
</Modal.Body>
<Modal.Footer>
<Button onClick={onClose}>Close</Button>
<Button variant="primary">Install</Button>
</Modal.Footer>
</Modal>
)
}
Props Interface Design
Clear and type-safe props interfaces:
interface ServiceCardProps {
service: Service
variant?: 'default' | 'compact' | 'detailed'
showActions?: boolean
onInstall?: (service: Service) => void
onFavorite?: (service: Service) => void
className?: string
}
function ServiceCard({
service,
variant = 'default',
showActions = true,
onInstall,
onFavorite,
className,
}: ServiceCardProps) {
// Component implementation
}
State Management Architecture
1. State Organization
// Global application state
interface AppState {
user: UserState
services: ServiceState
ui: UIState
auth: AuthState
}
// Feature-specific state
interface ServiceState {
items: Service[]
loading: boolean
error: string | null
filters: ServiceFilters
pagination: PaginationState
}
2. Store Patterns
Domain Stores
Each domain has its own store:
// User store
export const useUserStore = create<UserState>((set) => ({
user: null,
loading: false,
updateProfile: async (data) => {
set({ loading: true })
try {
const user = await updateUserProfile(data)
set({ user, loading: false })
} catch (error) {
set({ loading: false })
throw error
}
}
}))
// Service store
export const useServiceStore = create<ServiceState>((set) => ({
services: [],
loading: false,
fetchServices: async () => {
// Implementation
}
}))
UI State Store
Separate store for UI-specific state:
export const useUIStore = create<UIState>((set) => ({
sidebarOpen: false,
theme: 'light',
language: 'en',
toggleSidebar: () => set((state) => ({
sidebarOpen: !state.sidebarOpen
})),
setTheme: (theme) => set({ theme }),
setLanguage: (language) => set({ language })
}))
3. Data Synchronization
SWR Integration
Combine Zustand with SWR for data fetching:
function useServices() {
const { data, error, mutate } = useSWR('/api/services', fetchServices)
const setServices = useServiceStore((state) => state.setServices)
useEffect(() => {
if (data) {
setServices(data)
}
}, [data, setServices])
return {
services: data || [],
loading: !error && !data,
error,
refresh: mutate
}
}
Performance Architecture
1. Code Splitting Strategy
// Route-based splitting
const MarketplacePage = lazy(() => import('./marketplace/page'))
const ConsolePage = lazy(() => import('./console/page'))
const DashboardPage = lazy(() => import('./dashboard/page'))
// Component-based splitting
const ServiceModal = lazy(() => import('./components/ServiceModal'))
const AdminPanel = lazy(() => import('./components/AdminPanel'))
2. Optimization Techniques
Memoization
Strategic use of React.memo and useMemo:
// Memoized component
const ServiceCard = memo(function ServiceCard({ service }) {
const formattedPrice = useMemo(() =>
formatPrice(service.price), [service.price]
)
return (
<Card>
<h3>{service.name}</h3>
<p>{formattedPrice}</p>
</Card>
)
})
// Memoized selector
const useFilteredServices = () => {
const services = useServiceStore((state) => state.services)
const filters = useServiceStore((state) => state.filters)
return useMemo(() =>
filterServices(services, filters),
[services, filters]
)
}
Virtual Scrolling
For large lists:
import { FixedSizeList as List } from 'react-window'
function ServiceList({ services }) {
const Row = ({ index, style }) => (
<div style={style}>
<ServiceCard service={services[index]} />
</div>
)
return (
<List
height={600}
itemCount={services.length}
itemSize={200}
>
{Row}
</List>
)
}
3. Bundle Optimization
Tree Shaking
Ensure proper tree shaking:
// Good: Named imports
import { Button, Card } from '@nextui-org/react'
// Bad: Default import
import NextUI from '@nextui-org/react'
Dynamic Imports
Load features on demand:
// Dynamic feature loading
async function loadAdminFeatures() {
const { AdminPanel } = await import('./admin/AdminPanel')
const { UserManagement } = await import('./admin/UserManagement')
return { AdminPanel, UserManagement }
}
Security Architecture
1. Authentication Flow
// Auth context
interface AuthContext {
user: User | null
login: (credentials: LoginCredentials) => Promise<void>
logout: () => void
isAuthenticated: boolean
isAdmin: boolean
}
// Protected route wrapper
function ProtectedRoute({ children, requireAdmin = false }) {
const { isAuthenticated, isAdmin } = useAuth()
if (!isAuthenticated) {
return <Navigate to="/signin" />
}
if (requireAdmin && !isAdmin) {
return <Navigate to="/unauthorized" />
}
return children
}
2. Data Validation
// Input validation with Zod
import { z } from 'zod'
const ServiceSchema = z.object({
name: z.string().min(1).max(100),
description: z.string().min(10).max(500),
price: z.number().min(0),
category: z.enum(['ai', 'productivity', 'development'])
})
// Form validation
function ServiceForm() {
const { register, handleSubmit, formState: { errors } } = useForm({
resolver: zodResolver(ServiceSchema)
})
const onSubmit = (data) => {
// Data is automatically validated
createService(data)
}
return (
<form onSubmit={handleSubmit(onSubmit)}>
{/* Form fields */}
</form>
)
}
3. XSS Prevention
// Safe HTML rendering
import DOMPurify from 'dompurify'
function SafeHTML({ content }) {
const sanitizedContent = useMemo(() =>
DOMPurify.sanitize(content), [content]
)
return (
<div dangerouslySetInnerHTML={{ __html: sanitizedContent }} />
)
}
Testing Architecture
1. Testing Strategy
Unit Tests (70%)
├── Components
├── Hooks
├── Utilities
└── Stores
Integration Tests (20%)
├── API Integration
├── Component Integration
└── User Flows
E2E Tests (10%)
├── Critical User Journeys
├── Authentication Flows
└── Admin Functions
2. Test Organization
// Component test
describe('ServiceCard', () => {
const mockService = {
id: '1',
name: 'Test Service',
description: 'Test description',
price: 9.99
}
it('renders service information', () => {
render(<ServiceCard service={mockService} />)
expect(screen.getByText('Test Service')).toBeInTheDocument()
})
it('calls onInstall when install button is clicked', () => {
const onInstall = jest.fn()
render(<ServiceCard service={mockService} onInstall={onInstall} />)
fireEvent.click(screen.getByText('Install'))
expect(onInstall).toHaveBeenCalledWith(mockService)
})
})
// Hook test
describe('useServices', () => {
it('fetches services on mount', async () => {
const { result } = renderHook(() => useServices())
await waitFor(() => {
expect(result.current.services).toHaveLength(3)
})
})
})
Deployment Architecture
1. Build Process
// next.config.js
module.exports = {
output: 'standalone',
experimental: {
outputFileTracingRoot: path.join(__dirname, '../../'),
},
env: {
CUSTOM_KEY: process.env.CUSTOM_KEY,
},
}
2. Environment Configuration
// Environment-specific configs
const config = {
development: {
apiUrl: 'http://localhost:3001',
debug: true,
},
production: {
apiUrl: 'https://api.xpack.dev',
debug: false,
},
test: {
apiUrl: 'http://localhost:3001',
debug: false,
},
}
export default config[process.env.NODE_ENV || 'development']
3. Monitoring and Analytics
// Error tracking
import * as Sentry from '@sentry/nextjs'
Sentry.init({
dsn: process.env.SENTRY_DSN,
environment: process.env.NODE_ENV,
})
// Performance monitoring
export function reportWebVitals(metric) {
if (metric.label === 'web-vital') {
console.log(metric)
// Send to analytics service
}
}
This architecture provides a solid foundation for building scalable, maintainable, and performant web applications with modern React and Next.js patterns.