courseworx/docs/04-Component-Architecture.md

CourseWorx Component Architecture Documentation

📋 Document Information

• Version: 1.0.0
• Last Updated: 2024-12-19
• Author: AI Assistant
• Status: Draft - Ready for Review

🎯 Frontend Architecture Overview

CourseWorx frontend is built with React 18 using a component-based architecture. The application follows a hierarchical structure with clear separation of concerns between pages, components, and services.

🏗️ Component Structure

Directory Structure

frontend/src/
├── components/          # Reusable UI components
├── pages/              # Page-level components
├── contexts/           # React Context providers
├── services/           # API and external services
├── utils/              # Utility functions
└── App.js              # Main application component

📱 Page Components Analysis

1. CourseContent.js ⚠️ CRITICAL ISSUE

• Size: 1,736 lines
• Complexity: Extremely high
• Issues:
  • Mixed concerns (CRUD, UI, state management)
  • Multiple modals in single component
  • Complex state management
  • Difficult to maintain and test

Recommended Refactoring:

CourseContent.js (1,736 lines) → Split into:
├── CourseContentManager.js (Main container)
├── ContentList.js (Content display)
├── AddContentModal.js (Content creation)
├── EditContentModal.js (Content editing)
├── QuizQuestionsModal.js (Quiz management)
├── SectionManager.js (Section CRUD)
└── ContentDragDrop.js (Reordering)

2. CourseContentViewer.js ⚠️ NEEDS ATTENTION

• Size: 835 lines
• Issues:
  • Large component with mixed concerns
  • Complex state management
  • Multiple responsibilities

Recommended Refactoring:

CourseContentViewer.js (835 lines) → Split into:
├── ContentViewer.js (Main container)
├── ContentRenderer.js (Content display)
├── ProgressTracker.js (Progress management)
├── QuizRenderer.js (Quiz display)
└── NavigationControls.js (Content navigation)

3. Users.js ⚠️ NEEDS ATTENTION

• Size: 496 lines
• Issues:
  • User management mixed with UI
  • Complex filtering and pagination
  • Multiple modals

Recommended Refactoring:

Users.js (496 lines) → Split into:
├── UserManager.js (Main container)
├── UserList.js (User display)
├── UserFilters.js (Filtering)
├── AddUserModal.js (User creation)
└── UserActions.js (User operations)

4. Well-Structured Pages ✅

• Login.js (419 lines): Well-structured authentication
• Dashboard.js (396 lines): Good separation of concerns
• CourseDetail.js (424 lines): Appropriate size and structure

🧩 Reusable Components Analysis

1. Layout.js ✅ GOOD STRUCTURE

• Size: 163 lines
• Purpose: Main application layout
• Structure: Clean navigation and content area

2. CourseSidebar.js ✅ GOOD STRUCTURE

• Size: 346 lines
• Purpose: Course navigation sidebar
• Features: Collapsible sections, progress tracking

3. LoadingSpinner.js ✅ EXCELLENT

• Size: 18 lines
• Purpose: Loading state indicator
• Structure: Simple, focused, reusable

🔄 State Management Analysis

Current State Management

Global State:
├── AuthContext (Authentication)
├── React Query (Server state)
└── Local Component State

Issues:
├── No centralized state management
├── Props drilling in large components
└── Complex local state in large components

Recommended Improvements

Proposed State Management:
├── AuthContext (Keep as is)
├── React Query (Expand usage)
├── Context for UI state
└── Reduced local state

🔌 Service Layer Analysis

API Service Structure ✅ GOOD DESIGN

frontend/src/services/api.js:
├── authAPI
├── usersAPI
├── coursesAPI
├── courseContentAPI
├── courseSectionAPI
├── enrollmentsAPI
├── attendanceAPI
├── assignmentsAPI
├── lessonCompletionAPI
├── courseStatsAPI
└── userNotesAPI

Strengths:

• Clear separation by domain
• Consistent naming convention
• Proper error handling
• Request/response interceptors

🎨 Styling Architecture

Current Approach ✅ GOOD

• Tailwind CSS: Utility-first approach
• Consistent Design: Good use of design tokens
• Responsive: Mobile-first design

Component Styling Patterns

Consistent Patterns:
├── Button styles: bg-blue-600 hover:bg-blue-700
├── Form styles: Consistent input styling
├── Card styles: bg-white shadow rounded-lg
└── Text styles: Consistent typography scale

🧪 Component Testing Analysis

Current Testing Status ❌ CRITICAL GAP

• Unit Tests: None found
• Integration Tests: None found
• Component Tests: None found
• E2E Tests: None found

Recommended Testing Structure

Proposed Testing:
├── components/__tests__/
│   ├── LoadingSpinner.test.js
│   ├── Layout.test.js
│   └── CourseSidebar.test.js
├── pages/__tests__/
│   ├── Login.test.js
│   ├── Dashboard.test.js
│   └── CourseDetail.test.js
└── services/__tests__/
    └── api.test.js

🔧 Component Performance Analysis

Performance Issues Identified

1. Large Bundle Size: CourseContent.js affects initial load
2. No Code Splitting: All components loaded upfront
3. No Memoization: Potential re-render issues
4. Large Component Re-renders: Expensive updates

Performance Recommendations

Performance Improvements:
├── Code Splitting: React.lazy() for large components
├── Memoization: React.memo for expensive components
├── Bundle Analysis: webpack-bundle-analyzer
└── Virtual Scrolling: For large lists

📊 Component Complexity Metrics

Component Size Analysis

Component	Lines	Complexity	Status
CourseContent.js	1,736	Very High	❌ Refactor Required
CourseContentViewer.js	835	High	⚠️ Needs Attention
Users.js	496	Medium-High	⚠️ Needs Attention
CourseEdit.js	514	Medium-High	⚠️ Consider Refactoring
CourseCreate.js	482	Medium	✅ Acceptable
Login.js	419	Medium	✅ Good Structure

Complexity Thresholds

• < 200 lines: ✅ Good
• 200-400 lines: ⚠️ Monitor
• 400-600 lines: ⚠️ Consider refactoring
• > 600 lines: ❌ Refactor required

🔮 Recommended Component Architecture

1. Atomic Design Principles

Proposed Structure:
├── atoms/              # Basic UI elements
│   ├── Button.js
│   ├── Input.js
│   └── Icon.js
├── molecules/          # Simple component groups
│   ├── SearchBox.js
│   ├── UserCard.js
│   └── CourseCard.js
├── organisms/          # Complex component groups
│   ├── Header.js
│   ├── Sidebar.js
│   └── ContentList.js
├── templates/          # Page layouts
│   ├── DashboardLayout.js
│   └── CourseLayout.js
└── pages/              # Complete pages
    ├── Dashboard.js
    └── CourseDetail.js

2. Container/Presentation Pattern

Recommended Pattern:
├── containers/         # Logic and state
│   ├── CourseContainer.js
│   └── UserContainer.js
└── components/         # UI only
    ├── CourseList.js
    └── UserList.js

🚨 Critical Refactoring Priorities

Priority 1: CourseContent.js

• Impact: High - Core functionality
• Effort: High - Complex refactoring
• Timeline: Immediate - 2 weeks

Priority 2: CourseContentViewer.js

• Impact: Medium-High - User experience
• Effort: Medium - Moderate refactoring
• Timeline: After Priority 1 - 1 week

Priority 3: Users.js

• Impact: Medium - Admin functionality
• Effort: Medium - Moderate refactoring
• Timeline: After Priority 2 - 1 week

📋 Component Development Guidelines

1. Component Size Guidelines

• Maximum Lines: 300 lines per component
• Single Responsibility: One purpose per component
• Props Limit: Maximum 10 props per component

2. Naming Conventions

• Components: PascalCase (UserList.js)
• Files: Match component name
• Props: camelCase
• Event Handlers: on + Action (onUserClick)

3. Component Structure Template

// 1. Imports
import React, { useState, useEffect } from 'react';

// 2. Component definition
const ComponentName = ({ prop1, prop2, onAction }) => {
  // 3. State declarations
  const [state, setState] = useState(initialValue);
  
  // 4. Effects
  useEffect(() => {
    // Effect logic
  }, [dependencies]);
  
  // 5. Event handlers
  const handleAction = () => {
    // Handler logic
  };
  
  // 6. Render
  return (
    <div>
      {/* JSX */}
    </div>
  );
};

// 7. Export
export default ComponentName;

---

Next Steps:

1. Prioritize CourseContent.js refactoring
2. Implement component testing strategy
3. Establish component development guidelines
4. Create component library documentation