# ftfg777/clazzbridge-backend architecture

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

- Interactive diagram: https://gitdiagram.com/ftfg777/clazzbridge-backend
- Repository: https://github.com/ftfg777/clazzbridge-backend

## Overview

1. **What this repo is**
   - This repository is the **Spring Boot backend** for ClazzBridge, an academy/classroom management platform.
   - It exposes **REST APIs** for login, member/admin management, courses, classrooms, schedules, posts/Q&A, assignments/submissions, seats, and voting.
   - The README references a separate **React frontend** and a separate **Node.js/WebSocket chat service**; those are architectural neighbors, not the main code in this repo.

2. **Top-level backend shape**
   - The code follows a standard layered structure:
     - **controller** for HTTP entrypoints
     - **service** for business logic
     - **repository/mysql** for persistence
     - **domain** for JPA entities and relationships
     - **dto** for request/response contracts
     - **mapper** for entity/DTO conversion
     - **config**, **jwt**, and **exception** for cross-cutting concerns
   - This is a monolithic backend organized by feature domain rather than by generic infrastructure.

3. **Request flow**
   - A client request enters a **controller**.
   - The controller delegates to a **service**.
   - The service loads/saves entities through a **Spring Data JPA repository**.
   - The service returns DTOs, usually via a **MapStruct mapper**.
   - Errors are translated by **GlobalExceptionHandler** into API-level failures.
   - This makes the main architecture boundary: **HTTP/DTO layer → service layer → JPA persistence layer**.

4. **Security and authentication**
   - Authentication is built on **Spring Security + JWT**.
   - Key components:
     - `SecurityConfig`
     - `JwtFilter`
     - `LoginFilter`
     - `JwtUtil`
     - `CustomUserDetailService`
   - The auth flow supports **login, logout, access-token validation, and refresh-token handling**.
   - Role-based access control is central: different roles such as **manager, teacher, student** get different API permissions and data visibility.

5. **Main business domains**
   - The backend is split into functional areas that match the product features:
     - **Member/Admin** management
     - **Course/Classroom/Seat** administration
     - **Schedule/Calendar** operations
     - **Community posts, comments, board types**
     - **Q&A questions and answers**
     - **Assignments and submissions**
     - **Votes/polls**
     - **User profile**
   - Each area has its own controller/service/repository set, which is a strong clue for drawing separate bounded contexts in an architecture diagram.

6. **Core data model**
   - The `domain` package contains the persistent model.
   - Notable entities include:
     - `Member`, `MemberType`, `AvatarImage`
     - `Course`, `StudentCourse`, `TeacherCourse`
     - `Classroom`, `Seat`
     - `Schedule`
     - `Post`, `Comment`, `BoardType`
     - `Question`, `Answer`
     - `Assignment`, `Submission`, `SubmissionId`
     - `Vote`, `VoteOption`, `VoteResponse`
   - The presence of join entities like **StudentCourse** and **TeacherCourse** indicates many-to-many relationships are modeled explicitly.
   - `BaseTimeEntity` suggests shared created/modified auditing fields across entities.

7. **Persistence boundary**
   - The repo uses **Spring Data JPA** with a **MySQL** backend.
   - Repository interfaces under `repository/mysql` are the only persistence access path for relational data.
   - This implies the system relies on the database as the authoritative source for academy state: users, courses, schedules, boards, assignments, and voting.
   - The schema is likely initialized from the SQL scripts under `src/main/resources/sql`.

8. **DTO and mapping boundary**
   - The `dto` package is extensive and feature-specific, which shows the API is intentionally separated from the persistence model.
   - The `mapper` package uses **MapStruct** to convert between entities and DTOs.
   - This boundary reduces coupling between database shape and API contract, especially important for features like posts, questions, votes, and member profiles where response shapes differ from stored entities.

9. **Error handling and validation**
   - `GlobalExceptionHandler` centralizes API error translation.
   - Custom exception types exist for common and domain-specific cases such as:
     - unauthorized access
     - not found
     - file storage errors
     - post validation / state errors
     - assignment deadline violations
   - That means invalid role access and business-rule failures are treated as first-class architectural concerns, not just controller-level checks.

10. **Chat / real-time boundary**
   - There is a `domain/mongodb` package with `ChatRoom` and `Message`, but no full Mongo repository/service stack in this tree.
   - Combined with the README, this suggests real-time chat is handled by a **separate WebSocket/Redis service** or a partially split subsystem outside this repo.
   - In an architecture diagram, this repo should be shown as the **core REST backend**, with chat as an adjacent integration boundary rather than a fully internal module.

11. **Web presentation edge**
   - The repo is mostly API-first, but it also contains:
     - `src/main/resources/templates/profile.html`
     - static CSS under `static/css`
     - `WebConfig`
   - That indicates a small server-rendered/static presentation surface exists alongside the REST APIs, likely for profile-related UI or simple backend-served pages.

12. **Operational and delivery layer**
   - Build/runtime tooling:
     - **Gradle**
     - **Java 11**
     - **Spring Boot 2.7.3**
     - **Dockerfile**
     - **Jenkinsfile**
     - Kubernetes manifests: `back-deployment.yaml`, `back-service.yaml`
   - So the deployment path is containerized and CI/CD-driven, with Jenkins building the backend image and Kubernetes-style deployment/service resources defining runtime exposure.

13. **How to diagram the system**
   - The cleanest diagram is:
     - external clients/frontends at the top
     - Spring Security/JWT at the ingress boundary
     - feature controllers grouped by domain
     - shared service layer in the middle
     - JPA repositories and MySQL at the data layer
     - separate integration boundary for real-time chat/WebSocket/Redis
   - The key architectural theme is **a domain-driven Spring Boot monolith with strict DTO/service/repository separation and JWT-based role enforcement**.

Main entry points: [`src/main/java/com/example/academy/service`](https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/service) (Business Services), [`src/main/java/com/example/academy/config/SecurityConfig.java`](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/config/SecurityConfig.java) (Security Chain), [`src/main/java/com/example/academy/domain`](https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/domain) (Domain Model), [`src/main/java/com/example/academy/ProfileApplication.java`](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/ProfileApplication.java) (Application Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Core API"]
  node_n2["Auth APIs<br/>controller"]
  node_n3["Admin & Member<br/>controllers"]
  node_n4["Learning APIs<br/>controllers"]
  node_n5["Community APIs<br/>controllers"]
  node_n6["Workflows APIs<br/>controllers"]
end

subgraph group_g2["Security"]
  node_n7["Security Chain<br/>spring security"]
  node_n8["JWT Filters<br/>auth filters<br/>[JwtFilter.java]"]
  node_n9["User Details<br/>auth service"]
end

subgraph group_g3["Domain Data"]
  node_n10["API Contracts<br/>dto layer"]
  node_n11["Mappers<br/>mapstruct"]
  node_n12["Business Services<br/>service layer"]
  node_n13[("JPA Repositories<br/>mysql repositories")]
  node_n14{{"Domain Model<br/>jpa entities"}}
  node_n15[("MySQL<br/>relational db")]
end

subgraph group_g4["Integration"]
  node_n1(("REST Clients<br/>external clients"))
  node_n16[("Mongo Chat Model<br/>mongodb entities")]
  node_n17(("Chat Service<br/>websocket service"))
  node_n18["Web UI Surface<br/>server-rendered ui<br/>[profile.html]"]
end

subgraph group_g5["Delivery"]
  node_n19["Application Runtime<br/>spring boot app"]
  node_n20["Build & Deploy<br/>gradle/docker/k8s<br/>[build.gradle]"]
end

node_n1 -->|"authenticated by"| node_n7
node_n7 -->|"uses"| node_n8
node_n8 -->|"loads user"| node_n9
node_n7 -->|"protects"| node_n2
node_n7 -->|"protects"| node_n3
node_n7 -->|"protects"| node_n4
node_n7 -->|"protects"| node_n5
node_n7 -->|"protects"| node_n6
node_n2 -->|"delegates"| node_n12
node_n3 -->|"delegates"| node_n12
node_n4 -->|"delegates"| node_n12
node_n5 -->|"delegates"| node_n12
node_n6 -->|"delegates"| node_n12
node_n12 -->|"returns"| node_n10
node_n12 -->|"maps via"| node_n11
node_n12 -->|"persists through"| node_n13
node_n13 -->|"stores"| node_n14
node_n14 -->|"saved in"| node_n15
node_n12 -->|"reads/writes"| node_n14
node_n14 -.->|"adjacent model"| node_n16
node_n16 -.->|"integrates with"| node_n17
node_n18 -.->|"served to"| node_n1
node_n19 -->|"boots"| node_n7
node_n19 -->|"starts"| node_n12
node_n20 -.->|"builds"| node_n19
node_n20 -.->|"deploys with"| node_n15

click node_n2 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/AuthController.java"
click node_n3 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/AdminController.java"
click node_n4 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/CourseController.java"
click node_n5 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/PostController.java"
click node_n6 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/AssignmentController.java"
click node_n7 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/config/SecurityConfig.java"
click node_n8 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/jwt/JwtFilter.java"
click node_n9 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/service/CustomUserDetailService.java"
click node_n10 "https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/dto"
click node_n11 "https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/mapper"
click node_n12 "https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/service"
click node_n13 "https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/repository/mysql"
click node_n14 "https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/domain"
click node_n16 "https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/domain/mongodb"
click node_n18 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/resources/templates/profile.html"
click node_n19 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/ProfileApplication.java"
click node_n20 "https://github.com/ftfg777/clazzbridge-backend/blob/dev/build.gradle"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n2,node_n3,node_n4,node_n5,node_n6 toneBlue
class node_n7,node_n8,node_n9 toneAmber
class node_n10,node_n11,node_n12,node_n13,node_n14,node_n15 toneMint
class node_n1,node_n16,node_n17,node_n18 toneRose
class node_n19,node_n20 toneIndigo
```

## Components

### Core API

HTTP entrypoints and feature controllers for the academy backend

- [Auth APIs](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/AuthController.java): controller · Login, logout, token refresh, and auth endpoints · `src/main/java/com/example/academy/controller/AuthController.java`
- [Admin & Member](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/AdminController.java): controllers · Member management and admin-facing REST endpoints · `src/main/java/com/example/academy/controller/AdminController.java`
- [Learning APIs](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/CourseController.java): controllers · Courses, classrooms, schedules, seats, and enrollments · `src/main/java/com/example/academy/controller/CourseController.java`
- [Community APIs](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/PostController.java): controllers · Posts, comments, board types, and Q&A endpoints · `src/main/java/com/example/academy/controller/PostController.java`
- [Workflows APIs](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/controller/AssignmentController.java): controllers · Assignments, submissions, voting, and user profile endpoints · `src/main/java/com/example/academy/controller/AssignmentController.java`

### Security

JWT-based authentication and authorization

- [Security Chain](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/config/SecurityConfig.java): spring security · Request filtering and access control at the HTTP boundary · `src/main/java/com/example/academy/config/SecurityConfig.java`
- [JWT Filters](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/jwt/JwtFilter.java): auth filters · Login filter, JWT filter, and token utilities · `src/main/java/com/example/academy/jwt/JwtFilter.java`
- [User Details](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/service/CustomUserDetailService.java): auth service · Loads authenticated member identity and roles · `src/main/java/com/example/academy/service/CustomUserDetailService.java`

### Domain Data

Entities, repositories, and persistence-backed business state

- [API Contracts](https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/dto): dto layer · Feature-specific request and response DTOs · `src/main/java/com/example/academy/dto`
- [Mappers](https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/mapper): mapstruct · Entity-to-DTO and DTO-to-entity conversion layer · `src/main/java/com/example/academy/mapper`
- [Business Services](https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/service): service layer · Core application logic across auth, members, learning, community, and workflows · `src/main/java/com/example/academy/service`
- [JPA Repositories](https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/repository/mysql): mysql repositories · Spring Data access to the relational model · `src/main/java/com/example/academy/repository/mysql`
- [Domain Model](https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/domain): jpa entities · Members, courses, posts, assignments, votes, and related aggregates · `src/main/java/com/example/academy/domain`
- **MySQL**: relational db · Authoritative persistence store for academy state

### Integration

Adjacent runtime and presentation edges outside the main REST backend

- **REST Clients**: external clients · Frontend apps and API consumers calling the backend
- [Mongo Chat Model](https://github.com/ftfg777/clazzbridge-backend/tree/dev/src/main/java/com/example/academy/domain/mongodb): mongodb entities · ChatRoom and Message model for the separate chat boundary · `src/main/java/com/example/academy/domain/mongodb`
- **Chat Service**: websocket service · Adjacent real-time chat system referenced by the README
- [Web UI Surface](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/resources/templates/profile.html): server-rendered ui · Small static/templates surface alongside the REST API · `src/main/resources/templates/profile.html`

### Delivery

Build and deployment tooling

- [Application Runtime](https://github.com/ftfg777/clazzbridge-backend/blob/dev/src/main/java/com/example/academy/ProfileApplication.java): spring boot app · Main bootstrapping class and configuration entrypoint · `src/main/java/com/example/academy/ProfileApplication.java`
- [Build & Deploy](https://github.com/ftfg777/clazzbridge-backend/blob/dev/build.gradle): gradle/docker/k8s · Gradle build, Docker image, Jenkins pipeline, and Kubernetes manifests · `build.gradle`

## Connections

- REST Clients → Security Chain: authenticated by · Requests enter through the security chain before controllers
- Security Chain → JWT Filters: uses · Security config wires JWT login and request filtering
- JWT Filters → User Details: loads user · JWT and login flow resolve member identity and roles
- Security Chain → Auth APIs: protects · Authentication endpoints sit behind Spring Security
- Security Chain → Admin & Member: protects · Admin/member endpoints are role-gated
- Security Chain → Learning APIs: protects · Learning-management endpoints are authorized by role
- Security Chain → Community APIs: protects · Community endpoints are authorized by role
- Security Chain → Workflows APIs: protects · Workflow endpoints are authorized by role
- Auth APIs → Business Services: delegates · Controllers hand off work to the service layer
- Admin & Member → Business Services: delegates · Controllers hand off work to the service layer
- Learning APIs → Business Services: delegates · Controllers hand off work to the service layer
- Community APIs → Business Services: delegates · Controllers hand off work to the service layer
- Workflows APIs → Business Services: delegates · Controllers hand off work to the service layer
- Business Services → API Contracts: returns · Services shape API responses through DTO contracts
- Business Services → Mappers: maps via · MapStruct adapters convert between entity and DTO objects
- Business Services → JPA Repositories: persists through · Services use Spring Data repositories for relational access
- JPA Repositories → Domain Model: stores · Repositories operate on JPA entities and aggregates
- Domain Model → MySQL: saved in · Primary system of record is MySQL
- Business Services → Domain Model: reads/writes · Business logic works on the domain model
- Domain Model → Mongo Chat Model: adjacent model · MongoDB chat entities exist as a separate boundary
- Mongo Chat Model → Chat Service: integrates with · Chat model aligns with the separate realtime chat service
- Web UI Surface → REST Clients: served to · Static/templates surface is consumed by browser clients
- Application Runtime → Security Chain: boots · Application startup wires security and web infrastructure
- Application Runtime → Business Services: starts · Spring Boot application loads the service layer
- Build & Deploy → Application Runtime: builds · CI/CD and containerization package the backend runtime
- Build & Deploy → MySQL: deploys with · Kubernetes resources expose the backend service
