# laxmipriyapadegal2024/salespredict-customersegment architecture

> Architecture diagram of the GitHub repository laxmipriyapadegal2024/salespredict-customersegment, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/laxmipriyapadegal2024/salespredict-customersegment
- Repository: https://github.com/laxmipriyapadegal2024/salespredict-customersegment

## Overview

##### Project Type and Purpose
- This is a full-stack AI-powered web application for sales prediction and customer segmentation.
- Frontend: Next.js (React + TypeScript + TailwindCSS).
- Backend: FastAPI (Python) exposing REST endpoints and running ML pipelines.
- Database: Supabase (PostgreSQL) for metadata, raw data, predictions, and segments.

##### File Structure
- Top-level:
- docker-compose.yml – Locally orchestrates frontend, backend, and Postgres.
- frontend/ – Next.js app with pages under app/, reusable components, and lib/ for API clients.
- backend/ – FastAPI app with main.py, ml/ (models & preprocessing), routes/ (API endpoints), utils/ (Supabase client, file handling, response models), plus Dockerfile and .env examples.
- sample_data/ – Example CSVs for testing.
- Patterns:
- MVC-style separation: routes (controllers), utils (DB & file handlers), ml (services).
- Containerized services defined in docker-compose.yml.
- Environment-based configuration (.env files).

##### README for Insights
- Technical stack: Next.js 15, FastAPI, scikit-learn, XGBoost, Supabase.
- API endpoints for upload, sales prediction, segmentation.
- Supabase schema: tables for uploaded_files, sales_data, predictions, customer_data, customer_segments, segment_metadata.

a. Main Components
- User’s Browser / Mobile (UI)
- Next.js Frontend (React pages, components, API & Supabase client)
- FastAPI Backend
- Upload Service (upload_routes.py)
- Sales Prediction Service (sales_routes.py + ml/sales_regression.py + ml/preprocess.py)
- Customer Segmentation Service (segment_routes.py + ml/customer_segmentation.py)
- Database Utils (utils/database.py)
- External Database: Supabase (PostgreSQL)
- Machine Learning Libraries: scikit-learn, XGBoost
- Container Orchestration: Docker (Dockerfiles, docker-compose)

b. Relationships and Interactions
1. User interacts with the Next.js UI.
2. Next.js pages/components call internal API wrappers (lib/api.ts) to reach FastAPI endpoints (via NEXT_PUBLIC_API_URL).
3. FastAPI routes invoke:
- FileHandler to validate and store metadata in Supabase (uploaded_files).
- ML modules to preprocess data, train or predict.
- Database utils to read/write raw data, predictions, segments.
4. FastAPI persists results to Supabase tables.
5. Next.js fetches processed results (predictions, clusters) via API and renders charts (Recharts).

c. Architectural Patterns & Principles
- Layered Architecture: Presentation (Next.js), Application (FastAPI controllers), Business Logic (ML services), Persistence (Supabase).
- Single Responsibility: each route handles one endpoint; ML modules focus on algorithms; utils isolate DB/file concerns.
- Scalability via Docker containers and clear service boundaries.

d. Key Technologies / Frameworks
- Frontend: Next.js, React, TypeScript, TailwindCSS, Recharts, Supabase JS client.
- Backend: FastAPI, Uvicorn, Pydantic, scikit-learn, XGBoost, Supabase Python client.
- Database: Supabase (hosted PostgreSQL).
- Orchestration: Docker, docker-compose.

##### Essential Architectural Elements
- Environment variables (.env) feeding into Docker container configs.
- Supabase tables relevant to each service (uploaded_files, sales_data, predictions, etc.).
- Where static assets (sample_data, public/) live in the frontend.
- CI/CD/deployment hints (DEPLOYMENT.md, Dockerfiles).
- Don’t over-fragment: group related routes or utils under cohesive service blocks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    U["User Browser"]:::external
    U -->|interacts with| F

    %% Frontend Service
    subgraph "Frontend Service (Next.js)"
        direction TB
        F["Next.js Frontend"]:::frontend
        subgraph "Pages"
            direction TB
            LAYOUT["layout.tsx"]:::frontend
            PAGE["page.tsx"]:::frontend
            UPLOAD_PAGE["upload/page.tsx"]:::frontend
            DASH_PAGE["dashboard/page.tsx"]:::frontend
            SEG_PAGE["segmentation/page.tsx"]:::frontend
        end
        subgraph "Components"
            direction TB
            NAV["Navbar.tsx"]:::frontend
            FILEUP["FileUpload.tsx"]:::frontend
            SCHART["SalesChart.tsx"]:::frontend
            CCHART["ClusterChart.tsx"]:::frontend
            LOADER["Loader.tsx"]:::frontend
        end
        subgraph "Lib"
            direction TB
            API_CLIENT["api.ts"]:::frontend
            SUPA_CLIENT["supabaseClient.ts"]:::frontend
        end
        NEXTCONF["next.config.ts"]:::frontend
        PKGJSON["package.json"]:::frontend
        FDocker["Dockerfile"]:::orchestration
        F --> LAYOUT
        F --> PAGE
        F --> UPLOAD_PAGE
        F --> DASH_PAGE
        F --> SEG_PAGE
        F --> NAV
        F --> FILEUP
        F --> SCHART
        F --> CCHART
        F --> LOADER
        F --> API_CLIENT
        F --> SUPA_CLIENT
        F --> NEXTCONF
        F --> PKGJSON
        F --> FDocker
    end

    %% Backend Service
    subgraph "Backend Service (FastAPI)"
        direction TB
        B["FastAPI Backend"]:::backend

        subgraph "Upload Service"
            direction TB
            UP_ROUTE["upload_routes.py"]:::backend
            FILE_H["file_handler.py"]:::backend
            DB_META["database.py"]:::backend
            RESP_MODEL1["response_models.py"]:::backend
        end

        subgraph "Sales Prediction Service"
            direction TB
            SALES_ROUTE["sales_routes.py"]:::backend
            PREP1["preprocess.py"]:::ml
            ML_SALES["sales_regression.py"]:::ml
            DB_SALES["database.py"]:::backend
        end

        subgraph "Customer Segmentation Service"
            direction TB
            SEG_ROUTE["segment_routes.py"]:::backend
            PREP2["preprocess.py"]:::ml
            ML_SEG["customer_segmentation.py"]:::ml
            DB_SEG["database.py"]:::backend
        end

        subgraph "Database Utilities"
            direction TB
            DB_UTIL["database.py"]:::backend
            RESP_MODEL2["response_models.py"]:::backend
        end

        MAIN["main.py"]:::backend
        BDocker["Dockerfile"]:::orchestration
        ENV_EX[".env.example"]:::backend
        REQ_TXT["requirements.txt"]:::backend

        B --> MAIN
        B --> UP_ROUTE
        B --> SALES_ROUTE
        B --> SEG_ROUTE
        B --> FILE_H
        B --> DB_META
        B --> RESP_MODEL1
        B --> PREP1
        B --> ML_SALES
        B --> DB_SALES
        B --> PREP2
        B --> ML_SEG
        B --> DB_SEG
        B --> DB_UTIL
        B --> RESP_MODEL2
        B --> BDocker
        B --> ENV_EX
        B --> REQ_TXT
    end

    %% ML Modules Integration
    ML["ML Libraries\n(scikit-learn, XGBoost)"]:::ml
    SALES_ROUTE -->|uses| PREP1
    SALES_ROUTE -->|calls| ML_SALES
    SEG_ROUTE -->|uses| PREP2
    SEG_ROUTE -->|calls| ML_SEG
    PREP1 --> ML
    ML_SALES --> ML
    PREP2 --> ML
    ML_SEG --> ML

    %% Database
    DB["Supabase (PostgreSQL)"]:::db
    UP_ROUTE -->|store metadata| DB
    SALES_ROUTE -->|read/write sales_data & predictions| DB
    SEG_ROUTE -->|read/write customer_segments| DB
    DB_UTIL -->|utilizes| DB

    %% Frontend-Backend Interaction
    F -->|REST API calls| B
    B -->|JSON responses| F

    %% Sample Data
    SAMPLE["Sample Data (CSV)"]:::storage
    SAMPLE -->|for testing| UP_ROUTE

    %% Container Orchestration
    subgraph "Container Orchestration" 
        direction TB
        COMPOSE["docker-compose.yml"]:::orchestration
        FDocker
        BDocker
    end

    COMPOSE --> F
    COMPOSE --> B

    %% Click Events
    click LAYOUT "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/app/layout.tsx"
    click PAGE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/app/page.tsx"
    click UPLOAD_PAGE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/app/upload/page.tsx"
    click DASH_PAGE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/app/dashboard/page.tsx"
    click SEG_PAGE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/app/segmentation/page.tsx"
    click NAV "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/components/Navbar.tsx"
    click FILEUP "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/components/FileUpload.tsx"
    click SCHART "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/components/SalesChart.tsx"
    click CCHART "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/components/ClusterChart.tsx"
    click LOADER "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/components/Loader.tsx"
    click API_CLIENT "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/lib/api.ts"
    click SUPA_CLIENT "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/lib/supabaseClient.ts"
    click NEXTCONF "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/next.config.ts"
    click PKGJSON "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/frontend/package.json"
    click FDocker "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/tree/main/frontend/Dockerfile"
    click MAIN "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/main.py"
    click BDocker "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/tree/main/backend/Dockerfile"
    click ENV_EX "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/.env.example"
    click REQ_TXT "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/requirements.txt"
    click UP_ROUTE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/routes/upload_routes.py"
    click FILE_H "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/utils/file_handler.py"
    click DB_META "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/utils/database.py"
    click RESP_MODEL1 "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/utils/response_models.py"
    click SALES_ROUTE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/routes/sales_routes.py"
    click PREP1 "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/ml/preprocess.py"
    click ML_SALES "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/ml/sales_regression.py"
    click DB_SALES "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/utils/database.py"
    click SEG_ROUTE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/routes/segment_routes.py"
    click PREP2 "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/ml/preprocess.py"
    click ML_SEG "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/ml/customer_segmentation.py"
    click DB_SEG "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/utils/database.py"
    click DB_UTIL "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/utils/database.py"
    click RESP_MODEL2 "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/backend/utils/response_models.py"
    click COMPOSE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/docker-compose.yml"
    click SAMPLE "https://github.com/laxmipriyapadegal2024/salespredict-customersegment/blob/main/sample_data/sample_sales_data.csv"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E6FFE6,stroke:#028A0F,color:#028A0F
    classDef ml fill:#F3E6FF,stroke:#7D3C98,color:#7D3C98
    classDef db fill:#FFF5CC,stroke:#D4A017,color:#D4A017
    classDef orchestration fill:#F2F2F2,stroke:#666666,color:#333333
    classDef external fill:#FFFFFF,stroke:#000000,color:#000000
    classDef storage fill:#FFE6E6,stroke:#D93025,color:#D93025
```
