ocd-website/cline_docs/systemPatterns.md

# System Patterns: OCD Website

## Architecture Patterns

### Component Architecture
- **Atomic Design Methodology**
  - **Atoms**: Basic building blocks (buttons, inputs, icons)
  - **Molecules**: Simple groups of UI elements (form fields, cards)
  - **Organisms**: Complex UI components (navigation, forms)
  - **Templates**: Page layouts without specific content
  - **Pages**: Templates with real content

- **File Organization**
  - Components grouped by type (atoms, molecules, organisms)
  - Pages in Next.js app directory structure
  - Shared utilities in separate folders
  - Clear separation between frontend and backend

### State Management
- **React Context API** for global state
  - Authentication context for user sessions
  - UI context for theme and preferences
  - Toast notification context for system messages
- **Local component state** for UI-specific state
- **Form state** handled with controlled components
- **API state** managed with custom hooks

### Data Flow Patterns
- **Unidirectional data flow**
  - Props down, events up
  - Context providers at appropriate levels
- **Container/Presenter pattern**
  - Container components handle data fetching and state
  - Presenter components are pure rendering functions
- **Custom hooks** for reusable logic
  - useAuth for authentication
  - useFetch for data fetching
  - useForm for form handling

## Frontend Patterns

### Styling Approach
- **Utility-first CSS with Tailwind**
  - Consistent design tokens through Tailwind config
  - Custom utilities for project-specific needs
  - Component classes for common patterns
- **CSS variables for theming**
  - Core colors defined as CSS variables
  - Dark mode implementation using CSS variables
  - Responsive design using Tailwind breakpoints
- **Component-specific styles when needed**
  - Modules used for complex styling needs
  - Animation styles with Framer Motion

### Responsive Design
- **Mobile-first approach**
  - Default styles for mobile
  - Progressive enhancement for larger screens
- **Breakpoint system**
  - sm: 640px and up
  - md: 768px and up
  - lg: 1024px and up
  - xl: 1280px and up
  - 2xl: 1536px and up
- **Flexible layouts**
  - CSS Grid for page layouts
  - Flexbox for component layouts

### Form Handling
- **Controlled components** for form inputs
- **Field validation** with client-side validation
- **Error handling** with inline error messages
- **Form submission** with loading states
- **Accessibility considerations**
  - Proper labeling
  - Error association
  - Keyboard navigation

### Routing
- **Next.js App Router**
  - File-based routing for pages
  - Dynamic routes for entity details
  - Route groups for organization
  - Layouts for shared UI elements
- **Protected routes** for admin sections
  - Auth middleware
  - Redirect to login if unauthorized

## Backend Patterns

### API Design
- **RESTful endpoints**
  - Resource-based URLs
  - Appropriate HTTP methods
  - Consistent response format
  - Status codes for error handling
- **Controller pattern**
  - Route handlers for request parsing
  - Controllers for business logic
  - Services for reusable operations
  - Models for data access

### Authentication
- **JWT-based authentication**
  - JWTs stored in HTTP-only cookies
  - Short expiration with refresh tokens
  - CSRF protection with tokens
- **Permission-based authorization**
  - Role-based access control
  - Resource ownership checks
  - Fine-grained permissions

### Error Handling
- **Centralized error handling middleware**
  - Consistent error format
  - Appropriate status codes
  - Detailed error messages in development
  - Sanitized messages in production
- **Try/catch blocks** for async operations
- **Validation errors** for input validation

## Database Patterns

### Schema Design
- **Document-based design** for MongoDB
  - Embedded documents for related data
  - References for shared entities
  - Denormalization for performance
- **Validation schemas** with Mongoose
  - Required fields
  - Field types and constraints
  - Custom validators
- **Indexes** for frequently queried fields

### Query Patterns
- **Repository pattern** for data access
  - Encapsulated database operations
  - Reusable query methods
  - Consistent error handling
- **Pagination** for large collections
  - Limit/skip approach
  - Cursor-based pagination for efficiency
- **Filtering** with query parameters
  - Dynamic filter building
  - Validation of filter parameters

## Testing Patterns

### Unit Testing
- **Component testing** with React Testing Library
  - Component rendering
  - User interactions
  - State changes
- **Hook testing** with custom test utilities
- **Service testing** for business logic

### Integration Testing
- **API endpoint testing**
  - Request validation
  - Response structure
  - Error handling
- **Database interaction testing**
  - Create, read, update, delete operations
  - Schema validation
  - Indexing performance

### End-to-End Testing
- **User flow testing**
  - Critical user journeys
  - Form submissions
  - Authentication flows
- **Accessibility testing**
  - Automated a11y checks
  - Manual screen reader testing
  - Keyboard navigation testing

## Deployment Patterns

### Docker Containerization
- **Multi-stage builds** for production
  - Build stage for dependencies and compilation
  - Production stage for runtime
  - Minimal production image
- **Docker Compose** for local development
  - Service definitions
  - Volume mappings
  - Network configuration

### Environment Configuration
- **Environment-specific variables**
  - Development settings
  - Production settings
  - Testing settings
- **Secret management**
  - Environment variables for sensitive data
  - Docker secrets for production

## Accessibility Patterns

### WCAG 2.2 Compliance
- **Semantic HTML**
  - Proper heading hierarchy
  - Meaningful element choices
  - Landmark regions
- **ARIA attributes** when needed
  - Role definitions
  - State indications
  - Relationship attributes
- **Keyboard navigation**
  - Focus management
  - Logical tab order
  - Skip links
- **Screen reader support**
  - Alt text for images
  - Descriptive link text
  - Status announcements
- **Color contrast**
  - Meeting WCAG AA contrast ratios
  - Not relying on color alone
- **Motion sensitivity**
  - Respecting reduced motion preferences
  - Careful use of animations