AI Agentification Platform - Codebase Cleanup Plan

Date Created: 2025-12-24 Status: Planning Phase Priority: High

Executive Summary

This document outlines a comprehensive cleanup strategy for the AI Agentification Platform codebase. The project has grown organically and accumulated technical debt through rapid development cycles. This plan addresses database migrations, documentation sprawl, frontend/backend code organization, and establishes patterns for future maintenance.

Current State Analysis

1. Database & Migrations

Current State:

23 separate migration files in /supabase/migrations/
Additional standalone SQL files (schema.sql, maintenance_scripts.sql, etc.)
Multiple overlapping migration files fixing the same issues
Difficult to track the complete database schema

Issues Identified:

Migration file duplication (multiple RLS fixes, permission fixes)
Schema drift between migration files and schema.sql (59.5 KB)
Maintenance complexity when onboarding new developers
Difficult to establish fresh development environments

2. Documentation Files (103 MD Files)

Current State:

26 root-level documentation files
40+ files in /docs/ directory
10 archived phase documentation files
Multiple database documentation files
Scattered setup guides and deployment instructions

Issues Identified:

Duplicate/Overlapping Documentation:

Multiple deployment guides (DEPLOYMENT_*.md - 3 files)
Multiple setup guides (SETUP_*.md - 3 files)
Multiple SEO implementation docs (SEO_*.md - 7 files)
Multiple Supabase guides (SUPABASE_*.md - 2 files)
Database docs scattered across supabase/ and database/ directories

Outdated/Unnecessary Files:

docs/archive/ containing historical phase documentation (10 files)
FIX_*.md files that should be in issues or resolved
Phase-specific documentation no longer relevant
Individual feature summaries (NEWSLETTER_SETUP_SUMMARY.md, UI_UX_OVERHAUL_SUMMARY.md)

Poor Organization:

No clear documentation hierarchy
Root directory cluttered with technical docs
Unclear entry point for new developers (START_HERE.md vs README.md)

3. Frontend Code Organization

Current State:

146 JavaScript/TypeScript files
27 page components
20 shared components
12 custom hooks
23 service files

Issues Identified:

Component Duplication:

AdminLayout.jsx AND AdminLayoutV2.jsx (only one should exist)
AICourseCreator.jsx (44.8 KB) AND EnhancedAICourseCreator.jsx (31.8 KB)
Unclear which versions are active/deprecated

Large Component Files:

HomePage.jsx - 48.7 KB (likely doing too much)
ContentManager.jsx - 63.4 KB (god object anti-pattern)
AICourseCreator.jsx - 44.8 KB (needs decomposition)

Service Layer Issues:

23 service files - potential overlap/duplication
Mixed concerns (analytics.js, content.js, lessons.js may overlap)
No clear service organization pattern

Configuration Scattered:

Config files in both src/config/ and root level
Environment configuration mixed with application config

4. Backend Code Organization

Current State:

25 Python files
8 route files
Multiple service files
Mixed Flask/FastAPI patterns

Issues Identified:

API entry point unclear (api/index.py vs src/routes/)
Service duplication between Python backend and Supabase Edge Functions
Unclear responsibility boundaries between Python API and Edge Functions

Cleanup Strategy

Phase 1: Database Consolidation (Priority: CRITICAL)

Goal

Create a single, authoritative SQL file that represents the complete database schema and eliminates migration complexity.

Action Items

1.1 Export Current Production Schema

# Export the complete production schema
supabase db dump --schema public,auth,storage > supabase/COMPLETE_SCHEMA.sql

1.2 Create Master Migration File

File: supabase/migrations/00000000000000_complete_schema.sql
Contents: Complete schema including:
- All tables with proper structure
- All indexes and constraints
- All Row Level Security (RLS) policies
- All functions and triggers
- All realtime configurations
- Seed data for essential records (admin user, etc.)

1.3 Validation Strategy

Create fresh local Supabase instance
Apply only the new complete schema
Verify all functionality works
Run test suite against new schema
Compare with production schema for differences

1.4 Archive Old Migrations

# Move old migrations to archive
mkdir supabase/migrations/archive_2025_12_24
mv supabase/migrations/2*.sql supabase/migrations/archive_2025_12_24/

1.5 Clean Up Standalone SQL Files

Keep:

COMPLETE_SCHEMA.sql (new master file)
schema.sql (keep as reference for now)

Archive:

All individual migration files → migrations/archive_2025_12_24/
maintenance_scripts.sql → Document into runbook instead
verify_security.sql → Convert to automated test
Individual fix files → Archive

Benefits:

Single source of truth for database schema
Faster development environment setup (1 file vs 23)
Easier code review for schema changes
Reduced migration conflicts
Simpler rollback strategy

Phase 2: Documentation Consolidation (Priority: HIGH)

Goal

Create a clear, hierarchical documentation structure with no duplication and a single entry point.

Target Structure

/
├── README.md                          # Project overview, quick start
├── docs/
│   ├── README.md                      # Documentation index
│   ├── getting-started/
│   │   ├── installation.md            # Consolidated setup guide
│   │   ├── environment-setup.md       # All environment configs
│   │   └── quick-start.md             # Fast start for developers
│   ├── development/
│   │   ├── frontend-architecture.md   # React/Vite structure
│   │   ├── backend-architecture.md    # Python/Edge Functions
│   │   ├── database-schema.md         # Database design docs
│   │   └── coding-standards.md        # Style guide, patterns
│   ├── deployment/
│   │   ├── deployment-guide.md        # Consolidated deployment
│   │   ├── vercel-setup.md            # Vercel-specific
│   │   └── supabase-setup.md          # Supabase-specific
│   ├── features/
│   │   ├── ai-course-generation.md    # AI features
│   │   ├── authentication.md          # Auth system
│   │   ├── content-platform.md        # Content features
│   │   ├── course-management.md       # Course features
│   │   └── media-library.md           # Cloudinary integration
│   ├── integrations/
│   │   ├── cloudinary.md              # Media storage
│   │   ├── email-setup.md             # Email service
│   │   ├── analytics.md               # GA4, tracking
│   │   └── youtube-api.md             # Video integration
│   ├── seo/
│   │   └── seo-implementation.md      # Consolidated SEO guide
│   └── troubleshooting/
│       └── common-issues.md           # Known issues & fixes
├── supabase/
│   └── README.md                      # Database-specific docs only
└── Tech Overview/                     # High-level overviews
    ├── Ai Course Generation Overview.md
    ├── todo.md
    └── Cleanup.md (this file)

Consolidation Mapping

DELETE (Outdated/Unnecessary):

docs/archive/ (10 files) - Historical phase docs
FIX_*.md (2 files) - Should be GitHub issues or resolved
NEWSLETTER_SETUP_SUMMARY.md - Merge into features/email-setup.md
UI_UX_OVERHAUL_SUMMARY.md - Outdated implementation details
COLOR_PALETTE_REFERENCE.md - Move to design system or CSS variables
SECURITY_IMPROVEMENTS.md - Merge into development/security.md
Individual guide files in docs/guides/ that are feature summaries

CONSOLIDATE:

Current Files	Consolidate Into
DEPLOYMENT_*.md (3 files)	docs/deployment/deployment-guide.md
SETUP_*.md (3 files)	docs/getting-started/installation.md
SEO_*.md (7 files)	docs/seo/seo-implementation.md
SUPABASE_*.md (2 files)	docs/deployment/supabase-setup.md
supabase/DATABASE_SETUP_GUIDE.md supabase/MIGRATIONS_README.md supabase/migrations/README.md supabase/migrations/DEPLOYMENT_GUIDE.md database/SEEDING_GUIDE.md	docs/development/database-schema.md
docs/guides/CONTENT_PLATFORM_*.md (5 files)	docs/features/content-platform.md

KEEP & REORGANIZE:

README.md - Update with clear project overview
START_HERE.md - Merge into README.md or delete
CLOUDINARY_SETUP.md → docs/integrations/cloudinary.md
GA4_SETUP.md → docs/integrations/analytics.md
MEDIA_LIBRARY_GUIDE.md → docs/features/media-library.md
AI course creator docs → docs/features/ai-course-generation.md

Documentation Writing Standards

Going forward, all documentation should follow these principles:

Single Source of Truth - No duplicate docs for same topic
Feature-Based Organization - Group by feature, not by implementation phase
Clear Hierarchy - Max 3 levels deep
Dated & Versioned - Include "Last Updated" dates
Living Documents - Update existing docs rather than creating new ones
Code Examples - Include working code snippets
Link Rich - Cross-reference related docs

Phase 3: Frontend Code Cleanup (Priority: MEDIUM)

3.1 Resolve Component Duplication

AdminLayout Consolidation:

Action: Determine which is active (likely AdminLayoutV2.jsx)
- Review usage across admin pages
- Migrate any AdminLayout.jsx users to V2
- Delete AdminLayout.jsx
- Rename AdminLayoutV2.jsx → AdminLayout.jsx

AI Course Creator Consolidation:

Action: Determine active version
- EnhancedAICourseCreator.jsx (31.8 KB) appears newer
- Check which is referenced in admin routes
- Migrate to single implementation
- Delete deprecated version
- Document AI course generation workflow

3.2 Decompose Large Components

HomePage.jsx (48.7 KB)

Strategy: Break into smaller, focused components
- Extract hero section → components/home/HeroSection.jsx
- Extract features section → components/home/FeaturesSection.jsx
- Extract testimonials → components/home/TestimonialsSection.jsx
- Extract CTA section → components/home/CTASection.jsx
- Main HomePage.jsx becomes composition of sections

ContentManager.jsx (63.4 KB)

Strategy: Apply Single Responsibility Principle
- Extract content list → components/admin/content/ContentList.jsx
- Extract content editor → components/admin/content/ContentEditor.jsx
- Extract content filters → components/admin/content/ContentFilters.jsx
- Extract content actions → components/admin/content/ContentActions.jsx
- Main ContentManager.jsx becomes state coordinator

AICourseCreator.jsx (44.8 KB)

Strategy: Wizard step decomposition
- Extract step components → components/admin/ai-course/steps/
  - TopicSelectionStep.jsx
  - ContentSourceStep.jsx
  - CourseStructureStep.jsx
  - ReviewStep.jsx
- Extract AI config → components/admin/ai-course/AIConfigPanel.jsx
- Extract preview → components/admin/ai-course/CoursePreview.jsx

3.3 Service Layer Organization

Current Services (23 files) - Organize by Domain:

src/services/
├── api/                      # API clients
│   └── supabaseClient.js     # Move from lib/
├── auth/                     # Authentication
│   ├── authService.js
│   └── adminAuth.js
├── content/                  # Content management
│   ├── contentService.js
│   ├── lessonsService.js
│   ├── novaTracksService.js
│   └── marketingPageService.js
├── courses/                  # Course management
│   ├── coursesService.js
│   ├── enrollmentsService.js
│   └── progressService.js
├── media/                    # Media handling
│   ├── cloudinaryService.js
│   └── mediaLibraryService.js
├── analytics/                # Analytics & tracking
│   └── analyticsService.js
├── email/                    # Email services
│   ├── emailService.js       # (Python service)
│   └── newsletterService.js
├── utils/                    # Shared utilities
│   ├── logger.js
│   ├── errorHandler.js
│   └── validators.js
└── index.js                  # Service registry/exports

Deduplication Strategy:

Audit each service for overlapping functionality
Create shared base service class for common patterns
Consolidate duplicate API calls
Document service responsibilities

3.4 Configuration Consolidation

Current State:

Config scattered across src/config/, root, and inline

Target State:

src/config/
├── index.js              # Main config export
├── app.config.js         # App-wide settings
├── api.config.js         # API endpoints, keys
├── auth.config.js        # Auth providers, settings
├── seo.config.js         # SEO metadata
├── features.config.js    # Feature flags
└── environment.js        # Environment detection

Rules:

No hardcoded config values in components
All config imported from src/config/
Environment-specific values in .env files
Type-safe config with JSDoc or TypeScript

Phase 4: Backend Code Cleanup (Priority: MEDIUM)

4.1 Clarify API Architecture

Current Confusion:

Flask/FastAPI routes in src/routes/
API entry in api/index.py
Supabase Edge Functions in supabase/functions/

Clarification Strategy:

Define clear responsibilities:

Python Backend (src/routes/, api/):

Server-side email sending
Complex business logic requiring Python libraries
Scheduled tasks/cron jobs
Data processing pipelines

Supabase Edge Functions:

AI course generation (generate-course/)
Webhook handlers
Real-time data transformations
API proxying/orchestration

Decision Point:

Do we need Python backend at all?
Can Edge Functions handle everything?
Consider migrating Python routes to Edge Functions for simplification

Recommended Approach:

Option A (Keep Python):
  - Use Python only for email service, background jobs
  - Migrate simple CRUD to Supabase client-side
  - Clearly document why Python is needed

Option B (Full Serverless):
  - Migrate all Python routes to Edge Functions
  - Use Supabase Auth, RLS, and client SDK
  - Simpler deployment, better performance
  - Remove Python backend entirely

4.2 Service Consolidation

Python Services:

src/services/
├── email_service.py (20 KB)     # Email sending via provider
├── supabase_service.py (19 KB)  # Database operations
└── (other services)

Edge Function Services:

supabase/functions/generate-course/services/
├── crawler/      # Web scraping (Firecrawl, Tavily)
├── image/        # Image gen (DALL-E, Stability, Gemini)
├── llm/          # LLM providers (Claude, GPT, Gemini, Grok)
├── video/        # Video gen (HeyGen, Runway, Synthesia)
├── slides/       # Slide generation
└── nlp/          # NLP processing

Potential Duplication:

Check if Python supabase_service.py overlaps with client-side Supabase calls
Consider if email_service.py should be Edge Function instead

4.3 API Route Cleanup

Current Routes (8 files):

content.py, email.py, enrollments.py, lessons.py, newsletter.py, notifications.py, user.py, waitlist.py

Audit Questions:

Which routes are actively used?
Which can be replaced with Supabase client + RLS?
Which contain business logic that must stay server-side?
Are there duplicate routes in Edge Functions?

Cleanup Strategy:

Map all API endpoints to frontend usage
Identify unused routes → Delete
Document required server-side logic
Consolidate overlapping routes
Add OpenAPI/Swagger documentation

Phase 5: Code Quality & Standards (Priority: LOW)

5.1 Establish Coding Standards

Create .github/ directory:

.github/
├── CODE_STANDARDS.md         # Coding conventions
├── PULL_REQUEST_TEMPLATE.md  # PR template
├── CONTRIBUTING.md            # Contribution guide
└── workflows/
    ├── lint.yml               # Linting CI
    └── test.yml               # Testing CI

Frontend Standards:

ESLint configuration
Prettier formatting
Component naming conventions
File organization rules
Import order standards

Backend Standards:

PEP 8 compliance (Python)
Type hints required
Function documentation standards
Error handling patterns

5.2 Add Missing Tests

Current State:

Limited test coverage observed

Testing Strategy:

tests/
├── frontend/
│   ├── unit/              # Component tests
│   ├── integration/       # Feature tests
│   └── e2e/               # End-to-end tests
├── backend/
│   ├── test_routes.py     # API route tests
│   └── test_services.py   # Service tests
└── database/
    └── test_schema.sql    # Database tests

Priority Areas:

Authentication flows
Course enrollment logic
AI course generation
Payment processing (if applicable)
RLS policies validation

5.3 Performance Optimization

Audit & Optimize:

Large component files (HomePage, ContentManager)
Bundle size analysis with Vite
Database query optimization
Unnecessary re-renders
Image optimization strategy

5.4 Security Review

Actions:

Audit all RLS policies in new complete schema
Review API authentication mechanisms
Check for exposed secrets in codebase
Validate CORS configuration
Review admin role permissions

Implementation Roadmap

Week 1: Database Consolidation (CRITICAL PATH)

Day 1-2:

Export current production schema
Create COMPLETE_SCHEMA.sql with all tables, RLS, functions
Add seed data for admin user and essential records
Document schema design decisions

Day 3-4:

Test complete schema on fresh local Supabase instance
Verify all application features work with new schema
Run automated tests against new database
Compare with production for missing elements

Day 5:

Archive old migration files
Update deployment documentation
Create migration guide for existing databases
Git commit with clear message

Week 2: Documentation Cleanup

Day 1:

Create new docs/ directory structure
Set up documentation templates

Day 2-3:

Consolidate deployment guides
Consolidate setup guides
Consolidate SEO documentation
Consolidate database documentation

Day 4:

Consolidate feature documentation
Update README.md as main entry point
Delete archived and unnecessary files

Day 5:

Review all documentation for accuracy
Add cross-references and links
Update navigation and index pages

Week 3: Frontend Code Cleanup

Day 1-2:

Resolve AdminLayout duplication
Resolve AICourseCreator duplication
Delete unused components

Day 3-4:

Decompose HomePage.jsx
Decompose ContentManager.jsx
Decompose AICourseCreator.jsx

Day 5:

Reorganize services by domain
Consolidate configuration files
Update imports across codebase

Week 4: Backend Cleanup & Quality

Day 1-2:

Decide on Python backend vs full serverless
Audit and document all API routes
Remove unused routes
Consolidate duplicate services

Day 3:

Implement coding standards
Add ESLint/Prettier configs
Create PR templates

Day 4-5:

Add critical tests for auth and core features
Performance audit and optimizations
Security review
Final documentation update

Success Metrics

Quantitative Goals

Migrations: 23 files → 1 file (96% reduction)
Documentation: 103 files → ~25 files (75% reduction)
Component Files: Reduce files >10KB by breaking into smaller components
Code Duplication: Eliminate duplicate Admin components
Bundle Size: Reduce by at least 15% through tree-shaking unused code

Qualitative Goals

Developer Onboarding: New developer can set up environment in < 15 minutes
Documentation Clarity: Single entry point, clear navigation, no duplication
Code Maintainability: Clear component responsibilities, < 300 lines per file
Testing Coverage: Critical paths have automated tests
Deployment Speed: Faster deployments with simplified migrations

Risk Management

Risk: Breaking Production During Schema Migration

Mitigation:

Thoroughly test new schema in staging environment
Create backup of production database before migration
Plan migration during low-traffic window
Have rollback plan ready
Monitor error rates post-migration

Risk: Documentation Consolidation Loses Important Information

Mitigation:

Review all files before deletion
Keep archive of deleted files in git history
Have team review consolidated docs
Use git branches for documentation work

Risk: Frontend Refactoring Introduces Bugs

Mitigation:

Refactor one component at a time
Write tests before refactoring
Use feature flags for risky changes
Thorough QA testing
Staged rollout

Risk: Breaking Backend API Contracts

Mitigation:

Document all API endpoints before changes
Maintain API versioning
Coordinate with frontend team
Integration tests for API routes

Long-term Maintenance Strategy

Prevent Future Sprawl

Database:

All schema changes must update COMPLETE_SCHEMA.sql
No ad-hoc migrations without team review
Regular schema audits quarterly

Documentation:

Update existing docs rather than creating new ones
Quarterly documentation review and cleanup
Enforce "docs/ structure only" policy
Delete outdated docs immediately

Code:

PR template requires "file size check" for components >500 lines
Enforce service organization structure
Regular dependency audits
Automated linting in CI/CD

Governance

Code Review Standards:

All PRs must maintain cleanup standards
No duplicate components accepted
Documentation updates required for new features
Performance impact consideration

Regular Audits:

Monthly: Unused code detection
Quarterly: Documentation accuracy review
Quarterly: Dependency updates
Bi-annually: Full architecture review

Next Steps

Get Team Alignment
- Review this cleanup plan with team
- Prioritize phases based on business needs
- Assign owners to each phase
- Set timeline expectations
Create Tracking
- Create GitHub project for cleanup tasks
- Break down into individual issues
- Assign to team members
- Set up progress tracking
Execute Phase 1 (Database)
- This is highest priority
- Blocks other cleanup work
- Schedule for immediate execution
Communicate Progress
- Weekly cleanup status updates
- Document learnings and blockers
- Celebrate wins (files deleted, complexity reduced)

Appendix A: Files to Delete

Immediate Deletion Candidates (Low Risk)

Documentation (Archive these):

docs/archive/                           # 10 files - historical phase docs
FIX_*.md                                # 2 files - should be issues
NEWSLETTER_SETUP_SUMMARY.md             # Feature summary - merge into docs
UI_UX_OVERHAUL_SUMMARY.md               # Implementation summary - outdated
COLOR_PALETTE_REFERENCE.md              # Move to design system
SECURITY_IMPROVEMENTS.md                # Merge into security docs

Migration Files (After consolidation):

supabase/migrations/2*.sql              # 23 files → archive
create_media_library.sql                # Merge into COMPLETE_SCHEMA.sql
fix_anon_access.sql                     # Merge into COMPLETE_SCHEMA.sql
fix_media_library_rls.sql               # Merge into COMPLETE_SCHEMA.sql
verify_security.sql                     # Convert to automated test
fix_rls_for_sitemap.sql                 # Merge into COMPLETE_SCHEMA.sql
seed_admin_user.sql                     # Merge into COMPLETE_SCHEMA.sql
maintenance_scripts.sql                 # Document into runbook

Review Before Deletion (Medium Risk)

Components:

components/admin/AdminLayout.jsx         # If V2 is confirmed active
components/admin/AICourseCreator.jsx     # If Enhanced version is confirmed active

Services:

(Pending audit - identify duplicates and unused services)

Appendix B: Consolidation Templates

Template: Feature Documentation

# [Feature Name]

**Last Updated:** YYYY-MM-DD
**Status:** Active | Beta | Deprecated

## Overview
Brief description of the feature and its purpose.

## Architecture
How the feature is implemented technically.

## Setup & Configuration
Step-by-step setup instructions.

## Usage
How to use the feature with code examples.

## API Reference
Relevant API endpoints and parameters.

## Troubleshooting
Common issues and solutions.

## Related Documentation
- Link to related docs

Template: Deployment Guide

# [Deployment Target] Deployment Guide

**Last Updated:** YYYY-MM-DD

## Prerequisites
What you need before deploying.

## Environment Setup
How to configure environment variables.

## Deployment Steps
1. Step by step instructions
2. With actual commands
3. And expected outputs

## Verification
How to verify successful deployment.

## Rollback Procedure
How to rollback if deployment fails.

## Troubleshooting
Common deployment issues.

Conclusion

This cleanup plan represents a significant investment in code quality and maintainability. The payoff will be:

Faster Development: Clear code organization and documentation
Easier Onboarding: New developers productive in hours, not days
Reduced Bugs: Simpler codebase with fewer moving parts
Better Performance: Optimized bundle sizes and database queries
Lower Maintenance: Clear patterns prevent future sprawl

Estimated Effort: 4 weeks with dedicated focus ROI: Every week invested in cleanup saves 2-3 weeks of future debugging and confusion

Recommendation: Execute this plan incrementally, starting with Phase 1 (Database) as the highest priority. Each phase delivers independent value and can be tackled by different team members in parallel.

Plan Owner: [To be assigned] Last Updated: 2025-12-24 Next Review: After Phase 1 completion

Executive Summary​

Current State Analysis​

1. Database & Migrations​

2. Documentation Files (103 MD Files)​

3. Frontend Code Organization​

4. Backend Code Organization​

Cleanup Strategy​

Phase 1: Database Consolidation (Priority: CRITICAL)​

Goal​

Action Items​

Phase 2: Documentation Consolidation (Priority: HIGH)​

Goal​

Target Structure​

Consolidation Mapping​

Documentation Writing Standards​

Phase 3: Frontend Code Cleanup (Priority: MEDIUM)​

3.1 Resolve Component Duplication​

3.2 Decompose Large Components​

3.3 Service Layer Organization​

3.4 Configuration Consolidation​

Phase 4: Backend Code Cleanup (Priority: MEDIUM)​

4.1 Clarify API Architecture​

4.2 Service Consolidation​

4.3 API Route Cleanup​

Phase 5: Code Quality & Standards (Priority: LOW)​

5.1 Establish Coding Standards​

5.2 Add Missing Tests​

5.3 Performance Optimization​

5.4 Security Review​

Implementation Roadmap​

Week 1: Database Consolidation (CRITICAL PATH)​

Week 2: Documentation Cleanup​

Week 3: Frontend Code Cleanup​

Week 4: Backend Cleanup & Quality​

Success Metrics​

Quantitative Goals​

Qualitative Goals​

Risk Management​

Risk: Breaking Production During Schema Migration​

Risk: Documentation Consolidation Loses Important Information​

Risk: Frontend Refactoring Introduces Bugs​

Risk: Breaking Backend API Contracts​

Long-term Maintenance Strategy​

Prevent Future Sprawl​

Governance​

Next Steps​

Appendix A: Files to Delete​

Immediate Deletion Candidates (Low Risk)​

Review Before Deletion (Medium Risk)​

Appendix B: Consolidation Templates​

Template: Feature Documentation​

Template: Deployment Guide​

Conclusion​

Executive Summary

Current State Analysis

1. Database & Migrations

2. Documentation Files (103 MD Files)

3. Frontend Code Organization

4. Backend Code Organization

Cleanup Strategy

Phase 1: Database Consolidation (Priority: CRITICAL)

Goal

Action Items

Phase 2: Documentation Consolidation (Priority: HIGH)

Goal

Target Structure

Consolidation Mapping

Documentation Writing Standards

Phase 3: Frontend Code Cleanup (Priority: MEDIUM)

3.1 Resolve Component Duplication

3.2 Decompose Large Components

3.3 Service Layer Organization

3.4 Configuration Consolidation

Phase 4: Backend Code Cleanup (Priority: MEDIUM)

4.1 Clarify API Architecture

4.2 Service Consolidation

4.3 API Route Cleanup

Phase 5: Code Quality & Standards (Priority: LOW)

5.1 Establish Coding Standards

5.2 Add Missing Tests

5.3 Performance Optimization

5.4 Security Review

Implementation Roadmap

Week 1: Database Consolidation (CRITICAL PATH)

Week 2: Documentation Cleanup

Week 3: Frontend Code Cleanup

Week 4: Backend Cleanup & Quality

Success Metrics

Quantitative Goals

Qualitative Goals

Risk Management

Risk: Breaking Production During Schema Migration

Risk: Documentation Consolidation Loses Important Information

Risk: Frontend Refactoring Introduces Bugs

Risk: Breaking Backend API Contracts

Long-term Maintenance Strategy

Prevent Future Sprawl

Governance

Next Steps

Appendix A: Files to Delete

Immediate Deletion Candidates (Low Risk)

Review Before Deletion (Medium Risk)

Appendix B: Consolidation Templates

Template: Feature Documentation

Template: Deployment Guide

Conclusion