# qqv/cpt_edu architecture

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

- Interactive diagram: https://gitdiagram.com/qqv/cpt_edu
- Repository: https://github.com/qqv/cpt_edu

## Overview

##### Project Type & Purpose
- This is a full-stack application with a clear separation between the frontend (React using Material UI, Chart.js, and React Query) and the backend (Node.js and Express with MongoDB, along with GitHub API integration).
- The primary goal is to provide dashboards, analytics, and reporting on team progress and individual contributions, based on data fetched from GitHub and stored in MongoDB.

##### Main Components
a. Frontend Client:
- React application in the client directory.
- Key sub-components to include:
- Pages (for Dashboard, Analytics, Assistant, Login, etc.)
- Reusable UI components (like Sidebar and TeamCard).
- Contexts (like AuthContext.tsx) and services (for API interactions).
- Utility functions (for formatting dates, handling GitHub details, etc.)
b. Backend Server:
- Node.js application in the server directory.
- Modules such as:
- Controllers (even though not explicitly labeled, they are represented by the route handlers in the routes folder).
- API Routes (routes for auth, analytics, GitHub integration, team management, and user management).
- Models (Mongoose models for course, student, team, etc.).
- Middleware (for authentication, validation, error handling).
- Services (e.g., business logic in user.service.ts and GitHub-related services).
- Configuration (configs and environment specific settings like MongoDB URI, GitHub token).

c. External Services & Data Stores:
- MongoDB as your data storage layer.
- GitHub API integration for fetching and processing repository activity, commit data, etc.
- Environment configuration files that set the base URLs for API communication.

##### Relationships & Interactions
- The client sends requests to the backend APIs.
- In the backend, API routes interface with middleware and subsequently interact with services and database models.
- Calls from backend services to the GitHub API, showing external data integration.
- That authentication is enforced through middleware on the server, with context provided on the client to manage user state.

##### Architectural Patterns & Technologies
- Model-View-Controller (MVC) like pattern in the backend where models and routes (controllers) manage data and routing respectively.
- Separation of concerns:
- The client is responsible for UI rendering, state management, and API communication.
- The server handles API routing, business logic, middleware for authentication and error handling, and database interactions.
- Recognize external dependencies like GitHub APIs as essential integration points.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        F1["Frontend Client (React App)"]:::frontend
        F2["Pages"]:::frontend
        F3a["Sidebar"]:::frontend
        F3b["TeamCard"]:::frontend
        F4["Auth Context"]:::frontend
        F5["API Services"]:::frontend
        FP1["Date Format"]:::utility
        FP2["GitHub Helper"]:::utility
        FP3["Activity"]:::utility
    end

    %% Backend Layer
    subgraph "Backend Layer"
        B1["Backend API Server (Node/Express App)"]:::backend
        B2["Main Application"]:::backend
        B3["API Routes"]:::backend
        B4["Middleware"]:::backend
        B5["Services"]:::backend
        B6["Models"]:::backend
        B7["Configuration"]:::backend
    end

    %% External Components
    DB["MongoDB Database"]:::external
    G["GitHub API"]:::external

    %% Frontend Internal Relationships
    F1 -->|"contains"| F2
    F1 -->|"contains"| F3a
    F1 -->|"contains"| F3b
    F1 -->|"uses"| F4
    F1 -->|"calls"| F5
    F1 -->|"utilizes"| FP1
    F1 -->|"utilizes"| FP2
    F1 -->|"utilizes"| FP3

    %% Frontend to Backend Communication
    F1 -->|"APIRequests(HTTP)"| B1

    %% Backend Internal Relationships
    B1 -->|"initializes"| B2
    B2 -->|"defines"| B3
    B4 -->|"secures"| B3
    B3 -->|"invokes"| B5
    B5 -->|"processes"| B6
    B7 -->|"configures"| B1

    %% Backend to External Data Stores/Services
    B6 -->|"persists to"| DB
    B5 -->|"fetches from"| G

    %% Styles
    classDef frontend fill:#DDEEFF,stroke:#3366AA,stroke-width:2px;
    classDef backend fill:#FFEEDD,stroke:#AA6633,stroke-width:2px;
    classDef external fill:#E6FFE6,stroke:#339933,stroke-width:2px;
    classDef utility fill:#FFEECC,stroke:#CC8800,stroke-width:2px;

    %% Click Events for Frontend Components
    click F1 "https://github.com/qqv/cpt_edu/tree/main/client/"
    click F2 "https://github.com/qqv/cpt_edu/tree/main/client/src/pages/"
    click F3a "https://github.com/qqv/cpt_edu/blob/main/client/src/components/Sidebar.tsx"
    click F3b "https://github.com/qqv/cpt_edu/blob/main/client/src/components/TeamCard.tsx"
    click F4 "https://github.com/qqv/cpt_edu/blob/main/client/src/contexts/AuthContext.tsx"
    click F5 "https://github.com/qqv/cpt_edu/blob/main/client/src/services/api.ts"
    click FP1 "https://github.com/qqv/cpt_edu/blob/main/client/src/utils/dateFormat.ts"
    click FP2 "https://github.com/qqv/cpt_edu/blob/main/client/src/utils/github.ts"
    click FP3 "https://github.com/qqv/cpt_edu/blob/main/client/src/utils/activity.ts"

    %% Click Events for Backend Components
    click B1 "https://github.com/qqv/cpt_edu/tree/main/server/"
    click B2 "https://github.com/qqv/cpt_edu/blob/main/server/src/index.ts"
    click B3 "https://github.com/qqv/cpt_edu/tree/main/server/src/routes/"
    click B4 "https://github.com/qqv/cpt_edu/tree/main/server/src/middleware/"
    click B5 "https://github.com/qqv/cpt_edu/tree/main/server/src/services/"
    click B6 "https://github.com/qqv/cpt_edu/tree/main/server/src/models/"
    click B7 "https://github.com/qqv/cpt_edu/blob/main/server/src/config/index.ts"
```
