lad-website/cline_docs/systemPatterns.md

System Patterns: OCD Website

Architecture Patterns

Frontend Architecture

• Component Structure: Atomic Design methodology
  • Atoms: Buttons, inputs, icons, typography elements
  • Molecules: Forms, cards, navigation items, video player
  • Organisms: Navigation bar, page sections, footer
  • Templates: Page layouts with content placeholders
  • Pages: Complete views with actual content
• Data Flow: Unidirectional data flow (React standard)
• State Management: React Context API for global state
• Rendering Strategy:
  • Server-side rendering for initial page load and SEO
  • Client-side rendering for interactive components
  • Static generation for stable content
• Styling Approach:
  • Utility-first with Tailwind CSS
  • Component-specific styles via custom CSS
  • CSS variables for theming and consistency
• Responsive Design:
  • Mobile-first breakpoints (sm, md, lg, xl)
  • Container-based fluid layouts
  • Flexbox and CSS Grid for complex layouts

Backend Architecture

• API Design: RESTful with resource-based endpoints
• Controller Pattern: Route handlers separated from business logic
• Repository Pattern: Data access abstracted from controllers
• Middleware Stack:
  • Authentication/Authorization
  • Request validation
  • Error handling
  • Logging
  • CORS handling
• Data Models: MongoDB schemas with validation
• Service Layer: Business logic encapsulated in service modules

Key Technical Decisions

Next.js App Router

• File-based routing with nested layouts
• Server components for performance
• Client components marked with 'use client' for interactivity
• Metadata API for SEO optimization

Tailwind CSS 4.0

• JIT (Just-In-Time) compilation for optimal CSS bundle size
• Extended theme for custom design tokens
• CSS variables for runtime theming
• Utility-first approach for rapid development

Accessibility First

• WCAG 2.2 AA compliance as baseline requirement
• Semantic HTML structure
• ARIA attributes used appropriately
• Keyboard navigation focus management
• Screen reader announcements for dynamic content
• High contrast mode support
• Reduced motion option

Docker Containerization

• Multi-stage builds for production optimization
• Development environment consistency
• Separate containers for frontend, backend, and database
• Volume mounting for source code in development
• Environment variable management

JWT Authentication

• HTTP-only cookies for security
• Role-based access control
• Token refresh strategy
• Secure routes with middleware

Code Organization

Frontend Structure

frontend/
├── public/            # Static assets
├── src/
│   ├── app/           # Next.js routes and pages
│   ├── components/    # React components
│   │   ├── atoms/     # Basic UI elements
│   │   ├── molecules/ # Compound components
│   │   ├── organisms/ # Complex components
│   │   └── video/     # Video-related components
│   ├── hooks/         # Custom React hooks
│   ├── lib/           # Utility functions and helpers
│   ├── styles/        # Global styles and Tailwind config
│   └── types/         # TypeScript type definitions
└── tests/             # Test suites

Backend Structure

backend/
├── src/
│   ├── config/        # Configuration settings
│   ├── controllers/   # Request handlers
│   ├── middleware/    # Express middleware
│   ├── models/        # Data models and schemas
│   ├── routes/        # API route definitions
│   ├── services/      # Business logic
│   └── utils/         # Helper functions
└── tests/             # Test suites

Design Patterns

Component Composition

• Prefer composition over inheritance
• Small, focused components with single responsibilities
• Higher-order components for shared functionality
• Render props for flexible component APIs

Custom Hooks

• Extract reusable stateful logic into custom hooks
• Naming convention: use[HookName]
• Keep hooks focused on specific concerns

Error Handling

• Try/catch blocks in async functions
• Error boundaries for UI component failures
• Consistent error response format in API
• Detailed logging for debugging

Dependency Injection

• Service dependencies provided via parameters
• Loose coupling between modules
• Facilitates testing with mocks

Naming Conventions

Frontend

• Component Files: PascalCase.tsx
• Hook Files: camelCase.ts
• Utility Files: camelCase.ts
• CSS Modules: camelCase.module.css
• Component Props: interface ComponentNameProps

Backend

• Controllers: camelCase.controller.ts
• Models: PascalCase.model.ts
• Routes: camelCase.routes.ts
• Services: camelCase.service.ts
• Middleware: camelCase.middleware.ts

Testing Strategy

• Frontend:
  • Component tests with React Testing Library
  • E2E tests with Playwright
  • Visual regression tests
• Backend:
  • Unit tests for business logic
  • Integration tests for API endpoints
  • Mock database for testing

CI/CD Pipeline (Planned)

• GitHub Actions for automated builds
• Linting and type checking
• Automated testing
• Docker image building
• Deployment to production server