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

Admin Form Patterns

• Create/Edit/View pattern
  • Consistent page structure for entity management
  • Shared form components between create and edit
  • Read-only view pages with formatted data display
• Form state management
  • Local state for form data
  • Separate state for validation errors
  • Loading and submission states
• Validation strategies
  • Client-side validation before submission
  • Field-level validation on change/blur
  • Form-level validation on submit
  • Server-side validation as fallback
• Error recovery
  • Clear error messages
  • Preservation of valid form data
  • Ability to retry submission

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

API Integration Patterns

• Custom hooks for API interaction
  • Resource-specific hooks (useEvents, useMembers, etc.)
  • Standardized CRUD operations
  • Loading and error states
  • Pagination and filtering support
• Data transformation
  • Server-to-client format conversion
  • Date formatting for display
  • Consistent error handling
• Optimistic updates
  • Update UI before server confirmation
  • Rollback on error
  • Loading indicators during operations

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
• Admin API testing patterns
  • In-memory MongoDB for isolated tests
  • Mock authentication middleware
  • Comprehensive CRUD operation testing
  • Filter and pagination testing
  • Error case testing
  • Registration functionality testing

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