Frontend Architecture

Technology Stack

Core Technologies

• React 18 with TypeScript
• Redux Toolkit for state management
• React Router for navigation
• Socket.io for real-time updates
• Vite for development and building

UI Components

• Tailwind CSS for styling
• Shadcn UI component library
• Radix UI primitives
• Recharts for data visualization
• Lucide React for icons

Development Tools

• Storybook for component development
• ESLint and Prettier for code formatting
• MSW for API mocking
• Jest and Testing Library for testing

Application Structure

frontend/
├── src/
│   ├── app/            # Application setup & store
│   ├── components/     # React components
│   │   ├── atoms/     # Basic building blocks
│   │   ├── molecules/ # Simple components
│   │   ├── organisms/ # Complex components
│   │   ├── ui/        # Shadcn components
│   │   └── wrappers/  # HOCs and layouts
│   ├── hooks/         # Custom React hooks
│   ├── pages/         # Route components 
│   ├── services/      # API and state management
│   └── types/         # TypeScript definitions

Key Features

Authentication Flow

• Multiple auth methods:
  • Email/Password
  • GitHub OAuth
  • Personal access tokens
• JWT token management
• Protected route guards

Project Management

• Project creation and configuration
• Service deployment management
• Real-time status updates
• Resource monitoring

Domain Management

• Custom domain configuration
• SSL certificate handling
• DNS challenge verification
• Domain status monitoring

Real-time Updates

• WebSocket connection management
• Project status synchronization
• Service metrics streaming
• Connection status handling

State Management

Redux Store Structure

{
  auth: {
    token: string
    isAuth: boolean
    setupStep: number
  },
  config: {
    backendUrl: string
    githubConfig: {
      clientId: string
      clientSecret: string
    }
  }
}

API Integration

• RTK Query for data fetching
• Automatic cache management
• Optimistic updates
• Error handling

Component Architecture

Atomic Design Pattern

1. Atoms

   • Basic UI elements (buttons, inputs)
   • Typography components
   • Icons and visual elements

2. Molecules

   • Form groups
   • Navigation items
   • Status indicators

3. Organisms

   • Project cards
   • Service management panels
   • Configuration forms

Common Patterns

1. Form Handling

   const form = useForm<FormSchema>({
     resolver: zodResolver(schema),
     defaultValues: {},
   });
   

2. Data Fetching

   const { data, isLoading } = useQuery({
     queryKey: ['key'],
     queryFn: fetchData,
   });
   

3. WebSocket Integration

   useWebsockets({
     onMessage: handleMessage,
     onConnect: handleConnect,
   });
   

Routing Structure

<Routes>
  <Route path="/github" element={<GithubCallback />} />
  <Route element={<Layout />}>
    <Route index element={<Authentication />} />
    <Route path="setup" element={<Setup />} />
    <Route element={<AuthenticatedGuard />}>
      <Route path="dashboard" element={<Projects />} />
      <Route path="project/:projectId" element={<ProjectDetails />} />
    </Route>
  </Route>
</Routes>

Configuration Management

Environment Variables

VITE_API_URL=http://localhost:4000
VITE_SOCKET_URL=http://localhost:3001
VITE_GITHUB_CLIENT_ID=xxxxx

Feature Configuration

• Development/Production modes
• API endpoints
• WebSocket connections
• Authentication providers