How ftfg777/clazzbridge-backend works
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: service Business Services · SecurityConfig.java Security Chain · domain Domain Model · ProfileApplication.java Application Runtime
Components 20
Core API
HTTP entrypoints and feature controllers for the academy backend
- Auth APIs · Login, logout, token refresh, and auth endpoints
src/main/java/com/example/academy/controller/AuthController.java - Admin & Member · Member management and admin-facing REST endpoints
src/main/java/com/example/academy/controller/AdminController.java - Learning APIs · Courses, classrooms, schedules, seats, and enrollments
src/main/java/com/example/academy/controller/CourseController.java - Community APIs · Posts, comments, board types, and Q&A endpoints
src/main/java/com/example/academy/controller/PostController.java - Workflows APIs · Assignments, submissions, voting, and user profile endpoints
src/main/java/com/example/academy/controller/AssignmentController.java
Security
JWT-based authentication and authorization
- Security Chain · Request filtering and access control at the HTTP boundary
src/main/java/com/example/academy/config/SecurityConfig.java - JWT Filters · Login filter, JWT filter, and token utilities
src/main/java/com/example/academy/jwt/JwtFilter.java - User Details · 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 · Feature-specific request and response DTOs
src/main/java/com/example/academy/dto - Mappers · Entity-to-DTO and DTO-to-entity conversion layer
src/main/java/com/example/academy/mapper - Business Services · Core application logic across auth, members, learning, community, and workflows
src/main/java/com/example/academy/service - JPA Repositories · Spring Data access to the relational model
src/main/java/com/example/academy/repository/mysql - Domain Model · Members, courses, posts, assignments, votes, and related aggregates
src/main/java/com/example/academy/domain - MySQL · Authoritative persistence store for academy state
Integration
Adjacent runtime and presentation edges outside the main REST backend
- REST Clients · Frontend apps and API consumers calling the backend
- Mongo Chat Model · ChatRoom and Message model for the separate chat boundary
src/main/java/com/example/academy/domain/mongodb - Chat Service · Adjacent real-time chat system referenced by the README
- Web UI Surface · Small static/templates surface alongside the REST API
src/main/resources/templates/profile.html
Delivery
Build and deployment tooling
- Application Runtime · Main bootstrapping class and configuration entrypoint
src/main/java/com/example/academy/ProfileApplication.java - Build & Deploy · Gradle build, Docker image, Jenkins pipeline, and Kubernetes manifests
build.gradle
Connections 26
- 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