# ludanjubara/classroom architecture

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

- Interactive diagram: https://gitdiagram.com/ludanjubara/classroom
- Repository: https://github.com/ludanjubara/classroom

## Overview

##### Project Type and Purpose
- This is a full-stack web application built with Next.js (App Router + legacy Pages Router) for managing classrooms, students, teachers, subjects, and related entities.
- It exposes both RESTful API routes (under app/api and pages/api) and real-time Socket.IO endpoints (under pages/api/socket).

##### Main Components
A. Client (Browser / Next.js Front-End)
- Next.js App Router pages (under app/) use React Server Components and Client Components.
- Components and features (under components/ and features/) implement UI, fetch data, manage local state.
- State management via React Context (providers/) and Zustand stores (stores/).

B. Next.js Server
- API Layer:
– app/api/*: domain-driven REST endpoints (entity, auth, edgestore, statistics).
– pages/api/socket: real-time messaging via Socket.IO.
- Server-side logic: Prisma ORM (prisma/schema.prisma) connects to PostgreSQL (config/db.ts).
- Integration with external services:
– KindeAuth for authentication (app/api/auth).
– Edgestore for file storage (config/edgestore.ts, lib/edgestore-server.ts).
– OpenAI for insights and summaries (config/openai.ts).
– Custom statistics reporter (api/send-statistics.ts).

C. Database
- PostgreSQL (Prisma schema in prisma/schema.prisma).

D. External Services
- KindeAuth (OAuth / SSO).
- EdgeStore (file uploads & retrieval).
- OpenAI API (insight generation).
- Analytics/Statistics endpoint.

##### Relationships and Data Flows
- Browser → Next.js Server (HTTP): page navigation, data fetching via REST endpoints.
- Browser ↔ Socket.IO endpoint for chat messages (WebSocket).
- Next.js Server → Database (Prisma/SQL) for CRUD operations on classroom, user, message, etc.
- Next.js Server → Edgestore for file upload/download.
- Next.js Server → OpenAI for generating statistics or summaries.
- Next.js Server → Statistics service to send usage metrics.

##### Architectural Patterns & Design Principles
- Domain-driven folder structure: features/<domain> encapsulate API calls, hooks, components, types.
- Separation of concerns:
– UI (components/, views/)
– Business logic (features/)
– Data access (API routes, lib/, services/)
– State management (context/, stores/)
- Hybrid rendering: React Server Components (data‐fetching in app/) vs Client Components for interactivity.
- Serverless functions approach: each route file under app/api and pages/api is a discrete function.

##### Detailed Capture of Architecture
- How features modules (classrooms, community, notifications, etc.) plug into the API layer.
- Where server vs client code runs (Server Components, Client Components).
- Flow of user actions: e.g., “Teacher uploads assignment → app/api/edgestore upload route → Edgestore → returns URL → persisted in DB.”

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Presentation Layer"
        N1["Next.js App Router"]:::frontend
        N2["UI Components Library"]:::frontend
        N3["Feature Modules"]:::frontend
        N4["React Context Providers"]:::frontend
        N5["Zustand State Stores"]:::frontend
    end

    subgraph "Application Layer"
        subgraph "Auth Subsystem"
            A1["KindeAuth Routes"]:::back-end
        end
        subgraph "Entity APIs"
            B1["Domain REST Endpoints"]:::back-end
        end
        subgraph "Legacy APIs & Stats"
            C1["Legacy Pages API"]:::back-end
            C2["Statistics Reporter"]:::back-end
        end
        subgraph "Real-time Chat"
            R1["Socket.IO Server"]:::back-end
        end
        subgraph "File Storage"
            F1["Edgestore Routes"]:::back-end
            F2["Edgestore Config"]:::back-end
            F3["Edgestore Server SDK"]:::back-end
        end
        D1["Prisma ORM"]:::back-end
        D2["DB Config"]:::back-end
        E1["OpenAI Config"]:::back-end
    end

    subgraph "Data Layer"
        S1["PostgreSQL"]:::storage
        S2["EdgeStore"]:::external
        S3["OpenAI API"]:::external
        S4["Statistics Service"]:::external
    end

    %% Data Flows
    N1 -->|"HTTP"| A1
    N1 -->|"HTTP"| B1
    N1 -->|"HTTP"| C1
    N1 -->|"HTTP"| F1
    N1 -->|"HTTP"| C2
    N1 -->|"HTTP"| E1
    N1 -->|"WS"| R1

    A1 --> D1
    B1 --> D1
    C1 --> D1
    R1 --> D1

    F1 --> S2
    F2 --> F1
    F3 --> F1

    E1 --> S3
    C2 --> S4

    D1 --> S1
    D2 --> S1

    %% Click Events
    click N1 "https://github.com/ludanjubara/classroom/tree/main/app/"
    click N2 "https://github.com/ludanjubara/classroom/tree/main/components/"
    click N3 "https://github.com/ludanjubara/classroom/tree/main/features/"
    click N4 "https://github.com/ludanjubara/classroom/tree/main/context/"
    click N5 "https://github.com/ludanjubara/classroom/tree/main/stores/"
    click A1 "https://github.com/ludanjubara/classroom/tree/main/app/api/auth/"
    click B1 "https://github.com/ludanjubara/classroom/tree/main/app/api/"
    click C1 "https://github.com/ludanjubara/classroom/tree/main/pages/api/"
    click C2 "https://github.com/ludanjubara/classroom/blob/main/api/send-statistics.ts"
    click R1 "https://github.com/ludanjubara/classroom/tree/main/pages/api/socket/"
    click F1 "https://github.com/ludanjubara/classroom/blob/main/app/api/edgestore/[...edgestore]/route.ts"
    click F2 "https://github.com/ludanjubara/classroom/blob/main/config/edgestore.ts"
    click F3 "https://github.com/ludanjubara/classroom/blob/main/lib/edgestore-server.ts"
    click D1 "https://github.com/ludanjubara/classroom/blob/main/prisma/schema.prisma"
    click D2 "https://github.com/ludanjubara/classroom/blob/main/config/db.ts"
    click E1 "https://github.com/ludanjubara/classroom/blob/main/config/openai.ts"

    %% Styles
    classDef frontend fill:#e0f2e9,stroke:#333,stroke-width:1px
    classDef back-end fill:#e0e8f9,stroke:#333,stroke-width:1px
    classDef storage fill:#fff4e5,stroke:#333,stroke-width:1px
    classDef external fill:#f3e5ff,stroke:#333,stroke-width:1px
```
