# minh01-hub/classforge architecture

> Architecture diagram of the GitHub repository minh01-hub/classforge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/minh01-hub/classforge
- Repository: https://github.com/minh01-hub/classforge

## Overview

##### Project type and purpose
- From the file tree and README we see:
- A Next.js “app” folder with multiple pages (allocate, analytics, students).
- A “backend” folder with Python modules (models.py, routes.py, database.py) and a runner (run.py).
- UI components (components/*.tsx) and shared utilities (lib).
- The README title (“ClassForge-AI-Powered-Customizable-Classroom-Allocation-System-for-Schools”) plus folder names indicate a full-stack web application that:
- Presents a React/Next.js-based front-end for administrators/teachers.
- Calls a Python backend API to store data, perform allocation computations (AI/ML), and serve analytics.

##### File structure
Top-level directories:
- app/         ← Next.js 13 “app router” pages + global CSS/layout
- backend/     ← Python service implementing REST endpoints, DB models, config
- components/  ← Reusable React UI components and sub-UI libs
- lib/         ← Shared TypeScript types and utilities
- public/      ← Static assets
Configuration files:
- next.config.ts, tsconfig.json, postcss.config.mjs, eslint.config.mjs → Next.js build & lint setup
- package.json, package-lock.json → Front-end deps
- requirements.txt → Python backend deps

##### README for additional insights
- It’s a standard Next.js project with a custom title.

a. Main components
1. Frontend (Next.js app folder)
- Pages: Allocate, Analytics, Students
- UI Components: dashboard-shell, network-visualization, classroom-allocation, allocation-parameters, etc.
2. Backend (Python service)
- API Routes (backend/app/routes.py)
- Models & business logic (backend/app/models.py)
- Database layer (backend/database.py + config)
3. Database
- Likely PostgreSQL or SQLite (configured in backend/config.py)
4. Optional External AI/ML Service
- Could be an internal module or external API called by backend for optimization
5. Public assets/CDN (public folder, static files)
6. Client browsers (Users: Admin/Teacher)

b. Relationships & interactions
- Browser → Next.js Frontend:
– Fetch SSR pages & static JS/CSS assets
– Calls client-side handlers (e.g., dropdowns, visualization)
- Frontend ↔ Backend API (HTTP/REST or GraphQL):
– Allocate classrooms: POST parameters → /api/allocate endpoint
– Fetch analytics: GET → /api/analytics
– CRUD Students: /api/students
- Backend → Database:
– CRUD via ORM models.py
- (Optional) Backend → AI/ML engine (internal library or external service) for optimization algorithm
- Next.js build tools, CI/CD (Vercel) handle deployment

c. Architectural patterns & design principles
- Separation of concerns: UI vs business logic vs data persistence
- Next.js App Router for routing + server-side rendering & static generation
- RESTful API design in Python backend
- Modular React component library for UI consistency
- Environment-based config (backend/config.py, .env integration)
- Possible MVC pattern in backend: models.py, routes.py, database.py

d. Key technologies/frameworks
- Frontend: Next.js 13 (app router), React, TypeScript, PostCSS
- UI library: in-house components (components/ui/*)
- Backend: Python (likely Flask or FastAPI), SQLAlchemy (models.py), uvicorn/gunicorn (run.py)
- Database: relational (Postgres/SQLite)
- Deployment: Vercel (frontend), any Python host (Heroku/AWS)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Tier
    subgraph "User Tier"
        Browser["Browser (Admin/Teacher)"]:::external
    end

    %% Frontend Tier
    subgraph "Frontend Tier"
        subgraph "Next.js App Router"
            HomePage["Home Page"]:::frontend
            AllocatePage["Allocate Page"]:::frontend
            AnalyticsPage["Analytics Page"]:::frontend
            StudentsPage["Students Page"]:::frontend
            Layout["Global Layout"]:::frontend
            GlobalsCSS["Global Styles"]:::frontend
        end
        subgraph "UI Components - Dashboard & Layout"
            DashboardShell["Dashboard Shell"]:::frontend
            DashboardHeader["Dashboard Header"]:::frontend
            Navbar["Navbar"]:::frontend
            Sidebar["Sidebar"]:::frontend
            ModeToggle["Mode Toggle"]:::frontend
        end
        subgraph "UI Components - Allocation & Visualization"
            ClassroomAllocation["Classroom Allocation"]:::frontend
            AllocationParameters["Allocation Parameters"]:::frontend
            NetworkVisualization["Network Visualization"]:::frontend
        end
        subgraph "UI Library (components/ui)"
            UIAvatar["Avatar"]:::frontend
            UIBadge["Badge"]:::frontend
            UIButton["Button"]:::frontend
            UICard["Card"]:::frontend
            UIDropdown["Dropdown Menu"]:::frontend
            UIInput["Input"]:::frontend
            UILabel["Label"]:::frontend
            UIProgress["Progress"]:::frontend
            UIScroll["Scroll Area"]:::frontend
            UISlider["Slider"]:::frontend
            UISwitch["Switch"]:::frontend
            UITable["Table"]:::frontend
            UITabs["Tabs"]:::frontend
        end
        subgraph "Shared Frontend Utilities & Types (lib)"
            Utils["Utils"]:::frontend
            Types["Types"]:::frontend
        end
        CDN["CDN / Public Assets"]:::external
    end

    %% Backend Tier
    subgraph "Backend Tier"
        API["Python API Service"]:::backend
        subgraph "API Layer"
            Routes["Routes"]:::backend
        end
        subgraph "Business Logic"
            Models["Models & Logic"]:::backend
        end
        DatabaseInit["Database Init & ORM"]:::backend
        Config["Config"]:::backend
        Runner["App Runner"]:::backend
        AIEngine["AI/Optimization Engine"]:::external
    end

    %% Database
    Database["Database (PostgreSQL)"]:::database

    %% Connections - User to Frontend
    Browser -->|loads pages| HomePage
    Browser -->|navigates| AllocatePage
    Browser -->|navigates| AnalyticsPage
    Browser -->|navigates| StudentsPage
    Browser -->|fetches styles| GlobalsCSS
    Browser -.->|fetches static| CDN

    %% Frontend component composition
    HomePage -->|uses layout| Layout
    AllocatePage -->|uses layout| Layout
    AnalyticsPage -->|uses layout| Layout
    StudentsPage -->|uses layout| Layout

    Layout --> DashboardShell
    DashboardShell --> DashboardHeader
    DashboardShell --> Navbar
    DashboardShell --> Sidebar
    DashboardShell --> ModeToggle

    AllocatePage --> ClassroomAllocation
    AllocatePage --> AllocationParameters
    AllocatePage --> NetworkVisualization

    %% Frontend utilities & UI lib usage
    HomePage --> Utils
    AllocatePage --> Utils
    AnalyticsPage --> Utils
    StudentsPage --> Utils
    DashboardShell --> Types
    ClassroomAllocation --> Types
    UIAvatar --> Types

    %% Frontend to Backend API
    Browser -->|POST /api/allocate| API
    Browser -->|GET /api/analytics| API
    Browser -->|CRUD /api/students| API

    %% Backend internals
    API --> Routes
    Routes --> Models
    Models --> DatabaseInit
    DatabaseInit --> Database
    API -->|calls| AIEngine
    Runner --> API
    Runner --> Config
    Config --> DatabaseInit

    %% Click Events
    click HomePage "https://github.com/minh01-hub/classforge/blob/main/app/page.tsx"
    click AllocatePage "https://github.com/minh01-hub/classforge/blob/main/app/allocate/page.tsx"
    click AnalyticsPage "https://github.com/minh01-hub/classforge/blob/main/app/analytics/page.tsx"
    click StudentsPage "https://github.com/minh01-hub/classforge/blob/main/app/students/page.tsx"
    click Layout "https://github.com/minh01-hub/classforge/blob/main/app/layout.tsx"
    click GlobalsCSS "https://github.com/minh01-hub/classforge/blob/main/app/globals.css"
    click DashboardShell "https://github.com/minh01-hub/classforge/blob/main/components/dashboard-shell.tsx"
    click DashboardHeader "https://github.com/minh01-hub/classforge/blob/main/components/dashboard-header.tsx"
    click Navbar "https://github.com/minh01-hub/classforge/blob/main/components/navbar.tsx"
    click Sidebar "https://github.com/minh01-hub/classforge/blob/main/components/sidebar.tsx"
    click ModeToggle "https://github.com/minh01-hub/classforge/blob/main/components/mode-toggle.tsx"
    click ClassroomAllocation "https://github.com/minh01-hub/classforge/blob/main/components/classroom-allocation.tsx"
    click AllocationParameters "https://github.com/minh01-hub/classforge/blob/main/components/allocation-parameters.tsx"
    click NetworkVisualization "https://github.com/minh01-hub/classforge/blob/main/components/network-visualization.tsx"
    click UIAvatar "https://github.com/minh01-hub/classforge/blob/main/components/ui/avatar.tsx"
    click UIBadge "https://github.com/minh01-hub/classforge/blob/main/components/ui/badge.tsx"
    click UIButton "https://github.com/minh01-hub/classforge/blob/main/components/ui/button.tsx"
    click UICard "https://github.com/minh01-hub/classforge/blob/main/components/ui/card.tsx"
    click UIDropdown "https://github.com/minh01-hub/classforge/blob/main/components/ui/dropdown-menu.tsx"
    click UIInput "https://github.com/minh01-hub/classforge/blob/main/components/ui/input.tsx"
    click UILabel "https://github.com/minh01-hub/classforge/blob/main/components/ui/label.tsx"
    click UIProgress "https://github.com/minh01-hub/classforge/blob/main/components/ui/progress.tsx"
    click UIScroll "https://github.com/minh01-hub/classforge/blob/main/components/ui/scroll-area.tsx"
    click UISlider "https://github.com/minh01-hub/classforge/blob/main/components/ui/slider.tsx"
    click UISwitch "https://github.com/minh01-hub/classforge/blob/main/components/ui/switch.tsx"
    click UITable "https://github.com/minh01-hub/classforge/blob/main/components/ui/table.tsx"
    click UITabs "https://github.com/minh01-hub/classforge/blob/main/components/ui/tabs.tsx"
    click Utils "https://github.com/minh01-hub/classforge/blob/main/lib/utils.ts"
    click Types "https://github.com/minh01-hub/classforge/blob/main/lib/types.ts"
    click Routes "https://github.com/minh01-hub/classforge/blob/main/backend/app/routes.py"
    click Models "https://github.com/minh01-hub/classforge/blob/main/backend/app/models.py"
    click DatabaseInit "https://github.com/minh01-hub/classforge/blob/main/backend/database.py"
    click Config "https://github.com/minh01-hub/classforge/blob/main/backend/config.py"
    click Runner "https://github.com/minh01-hub/classforge/blob/main/backend/run.py"
    click CDN "https://github.com/minh01-hub/classforge/tree/main/public/"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#004d40
    classDef backend fill:#e8f5e9,stroke:#1b5e20,color:#2e7d32
    classDef database fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef external fill:#eceff1,stroke:#90a4ae,color:#455a64
```
