Lumina

Modern client–server application for CSV data analysis, modeling, and interactive visualizations.

Project Structure

lumina/
├── frontend/          # React/Vite frontend application
├── backend/           # Python FastAPI backend
└── README.md         # This file

Architecture Overview

Frontend (frontend/)

• Framework: React with Vite
• Language: TypeScript
• UI: Shadcn/ui components with Tailwind CSS
• API Client: Axios for backend communication
• Responsibilities:
  • User interface rendering
  • UI state management
  • API communication with backend

Backend (backend/)

• Framework: FastAPI (Python)
• Database: SQLite with SQLAlchemy ORM
• ML Libraries: Pandas, Scikit-learn, Plotly
• Responsibilities:
  • File upload handling
  • CSV data analysis
  • Machine learning model training
  • Data visualization generation
  • REST API endpoints

Getting Started

Prerequisites

• Node.js 18+ (for frontend)
• Python 3.8+ (for backend)

Development Setup

1. Backend Setup:

   cd backend
   pip install -r requirements.txt
   python -m app.db.init_db  # Initialize database
   python run.py             # Start server

   The API will be available at http://127.0.0.1:8000

2. Frontend Setup:

   cd frontend
   npm install
   npm run dev

   The frontend will be available at http://localhost:5173

API Documentation

Once the backend is running, visit:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc

Migration Guide

This project was refactored from a frontend-heavy architecture to a modern client-server architecture:

What Changed

Before (Frontend-Heavy)

• All business logic in React frontend (frontend/src/utils/)
• Supabase for database and file storage
• Direct database operations from frontend
• Client-side CSV parsing and analysis

After (Client-Server)

• Business logic moved to Python backend (backend/app/services/)
• Local SQLite database with SQLAlchemy ORM
• REST API for frontend-backend communication
• Server-side file processing and analysis

Migration Steps Completed

1. ✅ Project Restructuring: Created frontend/ and backend/ directories
2. ✅ Backend Scaffolding: Built FastAPI project with proper structure
3. ✅ Business Logic Migration: Ported TypeScript logic to Python services
4. ✅ API Endpoints: Created REST API for all operations
5. 🔄 Frontend Refactoring: Updated components to use backend API

Frontend Refactoring Pattern

The frontend components now follow this pattern:

// Before: Direct business logic
import { CSVAnalyzer } from '@/utils/csvAnalysis';
const analyzer = new CSVAnalyzer();
await analyzer.analyzeCSV(fileId);

// After: API calls
import { analysisApi } from '@/api/analysis';
await analysisApi.startAnalysis(fileId);
const results = await analysisApi.getAnalysisResults(fileId);

Key Files to Refactor

• frontend/src/components/FileUpload.tsx ✅ (Updated)
• frontend/src/components/analysis/DataProfileSection.tsx 🔄 (Example provided)
• frontend/src/components/analysis/ModelSection.tsx (Needs refactoring)
• frontend/src/components/analysis/VisualizationSection.tsx (Needs refactoring)
• frontend/src/components/AnalysisDashboard.tsx (Needs refactoring)

Next Steps

1. Remove Old Dependencies: Delete frontend/src/utils/ and frontend/src/integrations/supabase/
2. Update Components: Refactor remaining components to use API client
3. Add Error Handling: Implement proper error handling for API calls
4. Add Loading States: Show loading indicators during API operations
5. Test Integration: Ensure frontend and backend work together seamlessly

API Endpoints

Files

• POST /api/files/upload - Upload CSV file
• GET /api/files/ - List all files
• GET /api/files/{file_id} - Get file details
• DELETE /api/files/{file_id} - Delete file

Analysis

• POST /api/analysis/{file_id}/analyze - Start analysis
• GET /api/analysis/{file_id}/results - Get analysis results

Models

• POST /api/models/{file_id}/train - Train model
• GET /api/models/{file_id}/recommendations - Get recommendations
• GET /api/models/{file_id}/models - List trained models

Visualizations

• POST /api/visualizations/{file_id}/generate - Generate visualization
• GET /api/visualizations/{file_id}/auto - Generate auto visualizations