Architecture

Frontend Architecture

Overview#

The Haddock frontend is built with React and follows a feature-first architecture pattern, emphasizing modularity and reusability.

Directory Structure#

src/
├── app/              # App initialization
├── components/       # Shared components
├── features/         # Feature modules
│   ├── auth/
│   ├── projects/
│   └── vms/
├── hooks/           # Custom React hooks
├── lib/            # Utilities and helpers
├── pages/          # Route components
├── services/       # API services
└── types/         # TypeScript types

Core Technologies#

Framework#

• React 18+
• TypeScript
• Vite for building

State Management#

• Zustand for global state
• React Query for server state
• React Context for theme/auth

Styling#

• TailwindCSS
• Shadcn/ui components
• CSS Modules

Feature Organization#

Feature Module Structure#

features/projects/
├── api/           # API integration
├── components/    # Feature components
├── hooks/         # Feature hooks
├── stores/        # State management
└── types/        # Feature types

Data Flow#

Unidirectional Data Flow#

State Management#

Global State (Zustand)#

interface AppState {
  theme: 'light' | 'dark';
  setTheme: (theme: 'light' | 'dark') => void;
}

Server State (React Query)#

const { data: projects } = useQuery({
  queryKey: ['projects'],
  queryFn: fetchProjects
});

Component Architecture#

Atomic Design#

• Atoms (basic components)
• Molecules (component groups)
• Organisms (complex components)
• Templates (page layouts)
• Pages (route components)

Performance Optimization#

Code Splitting#

• Route-based splitting
• Component lazy loading
• Dynamic imports

Caching Strategy#

• React Query caching
• Service worker
• Local storage

Development Guidelines#

Component Guidelines#

• Write functional components
• Use TypeScript strictly
• Follow composable patterns
• Implement error boundaries

State Management Rules#

• Minimize global state
• Use local state when possible
• Implement proper cache invalidation
• Handle loading/error states

Styling Guidelines#

• Use utility-first approach
• Follow design tokens
• Maintain dark mode support
• Ensure responsive design