369 lines
11 KiB
Markdown
369 lines
11 KiB
Markdown
# EventBuzz Codebase Refactoring Analysis & Roadmap
|
|
|
|
## Executive Summary
|
|
|
|
This document provides a comprehensive analysis of the EventBuzz codebase, identifying patterns, duplications, and areas for improvement. Based on examining key components including `AgendaPage.tsx`, `ParticipantsPage.tsx`, `EventsPage.tsx`, `GlobalStubPage.tsx`, and supporting files, we've identified significant opportunities for refactoring to improve maintainability, scalability, and code quality.
|
|
|
|
## Analysis Date
|
|
March 2025
|
|
|
|
## Current Architecture Overview
|
|
|
|
### Tech Stack
|
|
- **Frontend**: React with TypeScript
|
|
- **Styling**: Inline styles with CSS variables
|
|
- **Routing**: Custom navigation system
|
|
- **State Management**: Component-local state only
|
|
- **Build Tool**: Vite
|
|
|
|
### Key Components Examined
|
|
1. `AgendaPage.tsx` (1200+ lines) - Event agenda management
|
|
2. `ParticipantsPage.tsx` (1000+ lines) - Participant management
|
|
3. `EventsPage.tsx` (1500+ lines) - Event listing and management
|
|
4. `GlobalStubPage.tsx` (2000+ lines) - Multiple stub pages (Design, Faculty, Forms, etc.)
|
|
5. `NavBar.tsx` - Event-specific navigation
|
|
6. `Sidebar.tsx` - Global navigation
|
|
7. `SettingsPage.tsx` - Organization settings
|
|
|
|
---
|
|
|
|
## Identified Issues & Patterns
|
|
|
|
### 1. Component Duplication
|
|
|
|
#### High-Frequency Duplications:
|
|
|
|
| Component | Files Found | Lines (approx) | Duplication Level |
|
|
|-----------|-------------|----------------|-------------------|
|
|
| `OverflowMenu` | 4+ files | 40-50 each | 95% identical |
|
|
| `ConfirmModal` | 2+ files | 30-40 each | 90% identical |
|
|
| Button styling patterns | All pages | N/A | Consistent patterns |
|
|
| Modal structures | Multiple | 100+ each | Similar patterns |
|
|
| Table/List patterns | Multiple | Varies | Similar implementations |
|
|
|
|
#### Specific Examples:
|
|
|
|
**OverflowMenu Duplication:**
|
|
- `AgendaPage.tsx` (lines ~150-200)
|
|
- `ParticipantsPage.tsx` (lines ~250-300)
|
|
- `EventsPage.tsx` (lines ~150-200)
|
|
- `GlobalStubPage.tsx` (lines ~100-150)
|
|
|
|
**ConfirmModal Duplication:**
|
|
- `AgendaPage.tsx` (lines ~800-850)
|
|
- `ParticipantsPage.tsx` (lines ~700-750)
|
|
|
|
### 2. Hardcoded Data & Configuration
|
|
|
|
#### Static Data Arrays:
|
|
```typescript
|
|
// Found in multiple files
|
|
const initialTracks: Track[] = [...]; // AgendaPage.tsx
|
|
const seedParticipants: Participant[] = [...]; // ParticipantsPage.tsx
|
|
const categories: Category[] = [...]; // EventsPage.tsx
|
|
const MOCK_SPEAKERS = [...]; // GlobalStubPage.tsx
|
|
const MOCK_ALL_PARTICIPANTS = [...]; // GlobalStubPage.tsx
|
|
```
|
|
|
|
#### Color & Style Mappings:
|
|
```typescript
|
|
// Repeated across files with similar patterns
|
|
const TYPE_STYLES: Record<SessionType, { bg: string; color: string }> = {...};
|
|
const STATUS_STYLES: Record<SessionStatus, { bg: string; color: string }> = {...};
|
|
const ROLE_STYLES: Record<Role, { bg: string; color: string }> = {...};
|
|
const TAG_COLORS: Record<string, { bg: string; color: string }> = {...};
|
|
```
|
|
|
|
### 3. Monolithic Components
|
|
|
|
**Large File Analysis:**
|
|
- `AgendaPage.tsx`: 1200+ lines, 15+ nested components
|
|
- `ParticipantsPage.tsx`: 1000+ lines, 10+ nested components
|
|
- `EventsPage.tsx`: 1500+ lines, 20+ nested components
|
|
- `GlobalStubPage.tsx`: 2000+ lines, 8+ page components
|
|
|
|
**Mixed Concerns:**
|
|
- UI rendering
|
|
- Data management
|
|
- Business logic
|
|
- Event handling
|
|
- State management
|
|
|
|
### 4. State Management Gaps
|
|
|
|
**Current State:**
|
|
- ✅ Component-local state only
|
|
- ❌ No global state management
|
|
- ❌ No API integration layer
|
|
- ❌ No data persistence
|
|
- ❌ No error handling patterns
|
|
- ❌ No loading states
|
|
|
|
### 5. Inconsistent Patterns
|
|
|
|
**Similar functionality, different implementations:**
|
|
- Filter components implemented differently across pages
|
|
- Search functionality with varying patterns
|
|
- Modal creation/editing flows
|
|
- Table vs card view toggles
|
|
|
|
---
|
|
|
|
## Refactoring Recommendations
|
|
|
|
### Phase 1: Foundation & Shared Components (High Impact)
|
|
|
|
#### 1.1 Create Shared Component Library
|
|
```
|
|
src/components/shared/
|
|
├── menus/
|
|
│ ├── OverflowMenu.tsx
|
|
│ └── ContextMenu.tsx
|
|
├── modals/
|
|
│ ├── ConfirmModal.tsx
|
|
│ ├── BaseModal.tsx
|
|
│ └── FormModal.tsx
|
|
├── badges/
|
|
│ ├── StatusBadge.tsx
|
|
│ ├── TypeBadge.tsx
|
|
│ └── RoleBadge.tsx
|
|
├── forms/
|
|
│ ├── InputField.tsx
|
|
│ ├── SelectField.tsx
|
|
│ └── ToggleField.tsx
|
|
└── layout/
|
|
├── EmptyState.tsx
|
|
├── LoadingState.tsx
|
|
└── ErrorBoundary.tsx
|
|
```
|
|
|
|
#### 1.2 Extract Common Patterns
|
|
- **Button styling system** - Consistent hover/focus states
|
|
- **Table/Row patterns** - Standardized data display
|
|
- **Card components** - Reusable card layouts
|
|
- **Filter components** - Unified filtering interface
|
|
|
|
### Phase 2: State Management & API Layer
|
|
|
|
#### 2.1 API Service Layer
|
|
```
|
|
src/services/
|
|
├── api/
|
|
│ ├── client.ts # HTTP client with interceptors
|
|
│ ├── events.ts # Event-related endpoints
|
|
│ ├── participants.ts # Participant endpoints
|
|
│ └── auth.ts # Authentication
|
|
├── mock/
|
|
│ ├── events.ts # Mock event data
|
|
│ ├── participants.ts # Mock participant data
|
|
│ └── index.ts # Mock API switch
|
|
└── types/
|
|
├── events.ts # Event type definitions
|
|
├── participants.ts # Participant type definitions
|
|
└── api.ts # API response types
|
|
```
|
|
|
|
#### 2.2 State Management Strategy
|
|
**Option A: React Context + useReducer**
|
|
- Simple, built-in solution
|
|
- Good for moderate complexity
|
|
|
|
**Option B: Zustand**
|
|
- Lightweight, scalable
|
|
- Good TypeScript support
|
|
|
|
**Recommended Structure:**
|
|
```
|
|
src/store/
|
|
├── events/
|
|
│ ├── slice.ts
|
|
│ └── actions.ts
|
|
├── participants/
|
|
│ ├── slice.ts
|
|
│ └── actions.ts
|
|
├── ui/
|
|
│ ├── slice.ts
|
|
│ └── actions.ts
|
|
└── index.ts
|
|
```
|
|
|
|
### Phase 3: Component Refactoring
|
|
|
|
#### 3.1 Split Monolithic Components
|
|
**AgendaPage.tsx Refactoring:**
|
|
```
|
|
src/components/agenda/
|
|
├── AgendaPage.tsx # Container component
|
|
├── TrackAccordion.tsx # Track section
|
|
├── SessionRow.tsx # List view row
|
|
├── SessionCard.tsx # Card view
|
|
├── SessionModal.tsx # Create/edit session
|
|
├── TrackModal.tsx # Create/edit track
|
|
└── hooks/
|
|
├── useAgendaData.ts # Data management
|
|
└── useAgendaActions.ts # Business logic
|
|
```
|
|
|
|
#### 3.2 Implement Container/Presenter Pattern
|
|
- **Container**: Manages data and logic
|
|
- **Presenter**: Handles UI rendering
|
|
- **Custom Hooks**: Extract reusable logic
|
|
|
|
### Phase 4: Configuration & Theming
|
|
|
|
#### 4.1 Centralized Configuration
|
|
```
|
|
src/config/
|
|
├── colors.ts # Color mappings
|
|
├── statusStyles.ts # Status badge styles
|
|
├── roleStyles.ts # Role badge styles
|
|
├── constants.ts # App constants
|
|
└── featureFlags.ts # Feature toggles
|
|
```
|
|
|
|
#### 4.2 Enhanced Theming System
|
|
- Extend beyond light/dark mode
|
|
- Support for custom brand colors
|
|
- Component-level theme variants
|
|
|
|
### Phase 5: Performance & Optimization
|
|
|
|
#### 5.1 Code Splitting
|
|
- Route-based code splitting
|
|
- Component lazy loading
|
|
- Dynamic imports for heavy components
|
|
|
|
#### 5.2 Memoization
|
|
- React.memo for pure components
|
|
- useMemo/useCallback for expensive computations
|
|
- Virtualized lists for large datasets
|
|
|
|
---
|
|
|
|
## Implementation Priority
|
|
|
|
### High Priority (Week 1-2)
|
|
1. **Extract OverflowMenu component** - Used in 4+ files
|
|
2. **Create shared modal components** - ConfirmModal, BaseModal
|
|
3. **Extract badge components** - StatusBadge, TypeBadge, RoleBadge
|
|
4. **Create API service layer** - Start with mock implementation
|
|
|
|
### Medium Priority (Week 3-4)
|
|
5. **Refactor AgendaPage** - Split into smaller components
|
|
6. **Implement Zustand store** - Global state management
|
|
7. **Create shared form components** - InputField, SelectField
|
|
8. **Add error boundaries** - Global error handling
|
|
|
|
### Low Priority (Week 5-6)
|
|
9. **Performance optimization** - Code splitting, memoization
|
|
10. **Enhanced theming** - Extended theme system
|
|
11. **Testing infrastructure** - Unit/integration tests
|
|
12. **Documentation** - Component documentation
|
|
|
|
---
|
|
|
|
## Technical Debt Assessment
|
|
|
|
### Critical Issues:
|
|
1. **No error handling** - API failures will crash app
|
|
2. **No loading states** - Poor user experience
|
|
3. **No data persistence** - Loss of state on refresh
|
|
4. **Large bundle size** - Monolithic components
|
|
|
|
### Maintenance Issues:
|
|
1. **High duplication** - Changes require multiple updates
|
|
2. **Tight coupling** - Hard to modify individual features
|
|
3. **No tests** - Regression risk with changes
|
|
4. **Mixed concerns** - Hard to reason about code
|
|
|
|
### Scalability Issues:
|
|
1. **Local state only** - Won't scale to complex workflows
|
|
2. **No API abstraction** - Hard to switch from mock data
|
|
3. **Inline styles** - Hard to maintain consistency
|
|
4. **No component documentation** - Onboarding difficulty
|
|
|
|
---
|
|
|
|
## Success Metrics
|
|
|
|
### Code Quality Metrics:
|
|
- **Reduction in lines of code**: Target 30% reduction
|
|
- **Increase in code reuse**: Target 40% shared components
|
|
- **Reduction in duplication**: Eliminate 90% of identified duplications
|
|
- **Improved test coverage**: Target 80% test coverage
|
|
|
|
### Performance Metrics:
|
|
- **Reduced bundle size**: Target 20% reduction
|
|
- **Faster initial load**: Target 30% improvement
|
|
- **Better Lighthouse scores**: Target 90+ in all categories
|
|
|
|
### Developer Experience:
|
|
- **Faster onboarding**: Reduced from days to hours
|
|
- **Easier modifications**: Single change points for common patterns
|
|
- **Better TypeScript support**: Full type safety across app
|
|
|
|
---
|
|
|
|
## Risk Assessment & Mitigation
|
|
|
|
### Risks:
|
|
1. **Regression bugs** - Breaking existing functionality
|
|
2. **Development slowdown** - Initial refactoring overhead
|
|
3. **Team adoption** - Resistance to new patterns
|
|
|
|
### Mitigation Strategies:
|
|
1. **Incremental refactoring** - Small, focused changes
|
|
2. **Comprehensive testing** - Automated test suite
|
|
3. **Documentation** - Clear migration guides
|
|
4. **Pair programming** - Knowledge sharing
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
### Immediate Actions:
|
|
1. Create shared component directory structure
|
|
2. Extract OverflowMenu as first shared component
|
|
3. Set up API service layer with mock data
|
|
4. Create basic error boundary component
|
|
|
|
### Short-term Goals (1 month):
|
|
1. Complete Phase 1 (shared components)
|
|
2. Implement basic state management
|
|
3. Refactor one major page (AgendaPage)
|
|
4. Add loading and error states
|
|
|
|
### Long-term Vision (3 months):
|
|
1. Full component library
|
|
2. Complete API integration
|
|
3. Performance optimization
|
|
4. Comprehensive testing suite
|
|
|
|
---
|
|
|
|
## Appendix: Detailed Component Analysis
|
|
|
|
### OverflowMenu Component Analysis:
|
|
**Current implementation**: 4 copies, ~40 lines each
|
|
**Proposed shared component**: 1 implementation, configurable via props
|
|
**Estimated savings**: 120+ lines of code
|
|
|
|
### Modal Pattern Analysis:
|
|
**Current**: Multiple modal implementations with similar structure
|
|
**Proposed**: BaseModal with composition, specialized modals extend
|
|
**Estimated savings**: 200+ lines of code
|
|
|
|
### Data Management Analysis:
|
|
**Current**: 5000+ lines of hardcoded mock data
|
|
**Proposed**: Centralized mock service, easy switch to real API
|
|
**Impact**: Enables backend integration without UI changes
|
|
|
|
---
|
|
|
|
## Contact & Updates
|
|
|
|
This document will be updated as refactoring progresses. For questions or suggestions, please contact the development team.
|
|
|
|
**Last Updated**: March 2025
|
|
**Version**: 1.0
|
|
**Status**: Analysis Complete - Ready for Implementation |