How triscravello/classpulse works
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