# triscravello/classpulse architecture

> Architecture diagram of the GitHub repository triscravello/classpulse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/triscravello/classpulse
- Repository: https://github.com/triscravello/classpulse

## Overview

##### Project Type & Purpose
- ClassPulse is a full-stack web application for tracking classroom behavior and generating reports.
- Frontend: React SPA with React Router, CSS Modules, Tailwind CSS.
- Backend: Node.js + Express.js REST API with JWT authentication.
- Database: MongoDB for persisting users, classes, students, and behavior logs.
- Reports export to CSV/PDF via PDFKit; charts rendered in frontend with Chart.js.

##### File Structure Analysis
- Top level:
- app.js/server.js – entry points for API server.
- config/db.js – MongoDB connection.
- controllers/ – request handlers (auth, class, student, behaviorLog, report).
- routes/v1/ – Express route definitions mapping HTTP paths to controllers.
- middleware/ – auth (JWT validation) and request validation.
- services/ – business logic abstracted from controllers (e.g., classService, authService).
- models/ – Mongoose schemas: User, Class, Students, BehaviorLogs.
- schemas/ – JOI validation schemas for incoming payloads.
- utils/ – helpers (generateToken, pdfExport).
- frontend/ – React app: public assets, src/components, pages, context, services (API wrappers), utils.
- Patterns:
- Layered architecture (HTTP → Middleware → Controller → Service → Model → DB).
- Client-server via REST.
- Separation of concerns: validation, business logic, data access.

a. Main Components
- User’s Browser (Client)
- React Frontend (SPA)
- Authentication Flow (JWT)
- Express.js API Server
- Controllers & Middleware
- Services Layer
- MongoDB Database
- External Libraries/Services (PDFKit, Chart.js)

b. Relationships & Data Flows
1. User interacts with React UI → React Router navigates to pages/components.
2. Components call frontend services (authService.js, api.js) → Axios sends HTTP requests to backend (e.g., POST /api/v1/auth/login).
3. API Gateway (Express.js) receives request → authMiddleware & validate.js run → controller invoked.
4. Controller calls corresponding service → service uses models (Mongoose) to query/update MongoDB.
5. PDF export or CSV generation uses utils/pdfExport. Service returns data → controller sends JSON or file stream back.
6. Frontend displays charts (Chart.js), updates UI, triggers download.

c. Architectural Patterns & Principles
- Layered Architecture: clear separation between HTTP layer, business logic, data access.
- Modularization: each domain (auth, student, class) has its own controllers, routes, schemas, services.
- Stateless JWT Authentication: token passed in HTTP headers.
- Validation-first: JOI schemas in middleware ensures data integrity.
- Component-based UI: reusable React components & CSS Modules.

d. Key Technologies & Frameworks
- React, React Router, Tailwind CSS, CSS Modules, Axios, Chart.js
- Node.js, Express.js, JWT, JOI, MongoDB (Mongoose)
- PDFKit for server-side PDF export

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["User Browser"]:::frontend
        ReactSPA["React SPA"]:::frontend
        Browser -->|interacts with| ReactSPA

        subgraph "React SPA"
            direction TB
            IndexJS["index.js"]:::frontend
            PublicHTML["public/index.html"]:::frontend
            AppRoutes["AppRoutes.js"]:::frontend
            UserContext["UserContext.js"]:::frontend
            APIUtils["api.js"]:::frontend
            NotifyUtils["notify.js"]:::frontend
            subgraph "Components"
                direction TB
                AuthComp["Auth Components"]:::frontend
                ClassroomComp["Classroom Components"]:::frontend
                DashboardComp["Dashboard Components"]:::frontend
                ReportsComp["Reports Components"]:::frontend
                CSSModules["CSS Modules"]:::frontend
            end
            IndexJS --> AppRoutes
            AppRoutes --> UserContext
            ReactSPA --> IndexJS
            ReactSPA --> PublicHTML
            ReactSPA --> APIUtils
            ReactSPA --> NotifyUtils
            ReactSPA --> AuthComp
            ReactSPA --> ClassroomComp
            ReactSPA --> DashboardComp
            ReactSPA --> ReportsComp
            ReactSPA --> CSSModules
        end

        ChartJS["Chart.js (Charts)"]:::external
        ReactSPA -->|renders charts| ChartJS
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        ExpressEntry["app.js & server.js"]:::backend
        ExpressEntry --> MiddlewareLayer
        subgraph "Middleware Layer"
            direction TB
            AuthMiddleware["authMiddleware.js"]:::backend
            ValidateMiddleware["validate.js"]:::backend
        end
        MiddlewareLayer --> ControllersLayer
        subgraph "Controllers Layer"
            direction TB
            AuthController["authController.js"]:::backend
            ClassController["classController.js"]:::backend
            StudentController["studentController.js"]:::backend
            BehaviorLogController["behaviorLogController.js"]:::backend
            ReportController["reportController.js"]:::backend
        end
        ControllersLayer --> RoutesLayer
        subgraph "Routes Layer"
            direction TB
            AuthRoutes["authRoutes.js"]:::backend
            ClassRoutes["classRoutes.js"]:::backend
            StudentRoutes["studentRoutes.js"]:::backend
            BehaviorLogRoutes["behaviorLogRoutes.js"]:::backend
            ReportRoutes["reportRoutes.js"]:::backend
        end
        ControllersLayer --> ServiceLayer
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        AuthService["authService.js"]:::service
        ClassService["classService.js"]:::service
        StudentService["studentService.js"]:::service
        BehaviorLogService["behaviorLogService.js"]:::service
        ReportService["reportService.js"]:::service
        APIService["services/api.js"]:::service
        UtilsLayer["Utils"]:::service
        subgraph "Utils"
            direction TB
            TokenUtil["generateToken.js"]:::service
            PDFExport["pdfExport.js"]:::service
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MongoDB["MongoDB"]:::database
    end

    %% Relations
    ReactSPA -->|HTTP requests| ExpressEntry
    AuthMiddleware --> AuthController
    ValidateMiddleware --> AuthController
    AuthController --> AuthService
    ClassController --> ClassService
    StudentController --> StudentService
    BehaviorLogController --> BehaviorLogService
    ReportController --> ReportService
    AuthService --> MongoDB
    ClassService --> MongoDB
    StudentService --> MongoDB
    BehaviorLogService --> MongoDB
    ReportService --> MongoDB
    ReportService --> PDFExport
    APIUtils --> ExpressEntry

    %% Click Events
    click ReactSPA "https://github.com/triscravello/classpulse/tree/main/frontend/src/"
    click AppRoutes "https://github.com/triscravello/classpulse/blob/main/frontend/src/AppRoutes.js"
    click APIUtils "https://github.com/triscravello/classpulse/blob/main/frontend/src/utils/api.js"
    click NotifyUtils "https://github.com/triscravello/classpulse/blob/main/frontend/src/utils/notify.js"
    click UserContext "https://github.com/triscravello/classpulse/blob/main/frontend/src/context/UserContext.js"
    click AuthComp "https://github.com/triscravello/classpulse/tree/main/frontend/src/components/auth/"
    click ClassroomComp "https://github.com/triscravello/classpulse/tree/main/frontend/src/components/classroom/"
    click DashboardComp "https://github.com/triscravello/classpulse/tree/main/frontend/src/components/dashboard/"
    click ReportsComp "https://github.com/triscravello/classpulse/tree/main/frontend/src/components/reports/"
    click CSSModules "https://github.com/triscravello/classpulse/tree/main/frontend/src/components/"
    click IndexJS "https://github.com/triscravello/classpulse/blob/main/frontend/src/index.js"
    click PublicHTML "https://github.com/triscravello/classpulse/blob/main/frontend/public/index.html"
    click ExpressEntry "https://github.com/triscravello/classpulse/blob/main/app.js"
    click ExpressEntry "https://github.com/triscravello/classpulse/blob/main/server.js"
    click AuthMiddleware "https://github.com/triscravello/classpulse/blob/main/middleware/authMiddleware.js"
    click ValidateMiddleware "https://github.com/triscravello/classpulse/blob/main/middleware/validate.js"
    click AuthController "https://github.com/triscravello/classpulse/blob/main/controllers/authController.js"
    click ClassController "https://github.com/triscravello/classpulse/blob/main/controllers/classController.js"
    click StudentController "https://github.com/triscravello/classpulse/blob/main/controllers/studentController.js"
    click BehaviorLogController "https://github.com/triscravello/classpulse/blob/main/controllers/behaviorLogController.js"
    click ReportController "https://github.com/triscravello/classpulse/blob/main/controllers/reportController.js"
    click AuthRoutes "https://github.com/triscravello/classpulse/blob/main/routes/v1/authRoutes.js"
    click ClassRoutes "https://github.com/triscravello/classpulse/blob/main/routes/v1/classRoutes.js"
    click StudentRoutes "https://github.com/triscravello/classpulse/blob/main/routes/v1/studentRoutes.js"
    click BehaviorLogRoutes "https://github.com/triscravello/classpulse/blob/main/routes/v1/behaviorLogRoutes.js"
    click ReportRoutes "https://github.com/triscravello/classpulse/blob/main/routes/v1/reportRoutes.js"
    click AuthService "https://github.com/triscravello/classpulse/blob/main/services/authService.js"
    click ClassService "https://github.com/triscravello/classpulse/blob/main/services/classService.js"
    click StudentService "https://github.com/triscravello/classpulse/blob/main/services/studentService.js"
    click BehaviorLogService "https://github.com/triscravello/classpulse/blob/main/services/behaviorLogService.js"
    click ReportService "https://github.com/triscravello/classpulse/blob/main/services/reportService.js"
    click APIService "https://github.com/triscravello/classpulse/blob/main/services/api.js"
    click TokenUtil "https://github.com/triscravello/classpulse/blob/main/utils/generateToken.js"
    click PDFExport "https://github.com/triscravello/classpulse/blob/main/utils/pdfExport.js"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724;
    classDef service fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef database fill:#fff3cd,stroke:#856404,color:#856404;
    classDef external fill:#f5c6cb,stroke:#721c24,color:#721c24;
```
