# megadiiiii/elms architecture

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

- Interactive diagram: https://gitdiagram.com/megadiiiii/elms
- Repository: https://github.com/megadiiiii/elms

## Overview

1. **Overall shape**
   - This is a single Spring Boot monolith for an Education/Learning Management System.
   - It uses a classic layered MVC architecture: controllers → services → repositories → database entities, with Thymeleaf server-side rendering for the UI.

2. **Application bootstrap and configuration**
   - `ElmsApplication.java` is the Spring Boot entry point.
   - Cross-cutting configuration lives under `config/` and `Security/`, including web MVC setup, Thymeleaf configuration, data seeding, password generation, and authentication failure handling.

3. **Presentation layer**
   - The main UI is rendered from Thymeleaf templates in `src/main/resources/templates`.
   - The UI is organized by domain areas: admin, class, grade, student, materials, profile, and common pages like login, homepage, attendance, schedule, and contact.
   - Shared UI fragments and layouts are separated into `templates/fragments` and `templates/layouts`, indicating a reusable page shell rather than API-only responses.

4. **Request handling boundaries**
   - Controllers are organized by feature: `StudentController`, `StaffController`, `ClassController`, `CourseController`, `GradeController`, `MaterialController`, `ProfileController`, `ContactController`, `UserPageController`, and `AdminGradeController`.
   - These controllers are the boundary between the browser-facing pages/forms and the application services.
   - The presence of both “admin” and “my-*” pages suggests role-specific views for administrators, staff, and students.

5. **Security and identity**
   - Spring Security is a major architectural boundary.
   - `SecurityConfig` and `CustomAuthenticationFailureHandler` define login/access behavior.
   - `CustomUserDetails` and `UserDetailsServiceImpl` bridge persisted user records into Spring Security’s authentication model.
   - Domain roles and statuses are modeled explicitly in `constant/` and `models/Role.java`, `models/User.java`.

6. **Domain model**
   - Core entities live in `models/`: `User`, `Role`, `StudentProfile`, `StaffProfile`, `Course`, `ClassEntity`, `ClassSession`, `Schedule`, `Attendance`, `Grade`, and `LessonMaterial`.
   - The model suggests the system tracks academic structure, attendance, grades, schedules, and course materials, with user accounts linked to student/staff profiles.

7. **Persistence layer**
   - Repository interfaces under `repository/` provide data access for each entity type.
   - This is likely Spring Data JPA-backed persistence, with repositories as the only direct database boundary.
   - Separate repositories for `ClassSession`, `Schedule`, `Attendance`, `Grade`, and `LessonMaterial` show that operational records are stored independently from master data like users, classes, and courses.

8. **Service layer**
   - Business logic is concentrated in service interfaces and implementations under `services/` and `services/impl/`.
   - Each major domain area has a dedicated service: user, student, staff, class, course, attendance, grade, material, and email.
   - `EmailServiceImpl` indicates outbound email is part of the system’s workflow, likely for notifications or account-related actions.

9. **DTO and mapping boundary**
   - The app does not expose entities directly at the controller boundary; instead it uses request/response DTOs in `dto/` and mappers in `mapper/`.
   - Request DTOs cover form submissions for classes, students, staff, grades, attendance, and materials.
   - Response DTOs provide view-specific projections like summaries, details, schedules, and role info, which keeps UI payloads separate from persistence models.

10. **Feature subsystems**
    - **Student management:** student form, detail, list pages plus student DTOs/services/repository.
    - **Staff management:** staff form/detail/admin pages plus staff DTOs/services/repository.
    - **Class and scheduling:** class pages, class sessions, schedules, and class summaries.
    - **Grades and attendance:** grade input/view pages and attendance forms/records.
    - **Materials:** lesson material creation and preview/listing, with client-side support in `static/js/materials.js` and PDF viewing support.
    - **Profile and self-service views:** profile update/view, personal attendance, grades, and schedule pages.

11. **Static assets and browser-side support**
    - Static assets live under `static/` for CSS, JavaScript, images, and a PDF viewer library.
    - The presence of `countries.json` suggests some forms use client-side reference data.
    - Most functionality still appears server-rendered, with JavaScript used selectively for interactions around materials and previews.

12. **Initialization and seed data**
    - `DataInit.java` likely prepares initial domain data such as roles, users, or reference entities at startup.
    - `PasswordGenerator.java` suggests automated credential setup or provisioning support during initialization or admin workflows.

13. **File storage boundary**
    - The `uploads/avatars` directory indicates the system stores uploaded files on disk rather than exclusively in the database.
    - Combined with materials and avatar-related templates/controllers, this implies a local filesystem boundary for user images and possibly lesson assets.

14. **Testing and operational footprint**
    - There is a minimal test scaffold in `src/test/java`, indicating the repo is set up for Spring Boot testing but not heavily populated in the tree shown.
    - Overall, the architectural diagram should show one deployable application with internal modules for web, security, services, persistence, and file/email integrations, rather than multiple services.

Main entry points: [`src/main/java/com/megadiiiii/elms/controller`](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/controller) (Controllers), [`src/main/java/com/megadiiiii/elms/repository`](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/repository) (Repositories), [`src/main/java/com/megadiiiii/elms/dto`](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/dto) (DTOs & Mappers), [`src/main/java/com/megadiiiii/elms/services/MaterialService.java`](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/MaterialService.java) (Materials)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application"]
  node_bootstrap(("ELMS app<br/>Spring Boot entrypoint"))
  node_config["Config"]
  node_security["Security<br/>auth boundary"]
end

subgraph group_web["Web Layer"]
  node_controllers["Controllers"]
  node_student_ctrl["Student"]
  node_class_ctrl["Class"]
  node_grade_ctrl["Grades<br/>grade controller"]
  node_material_ctrl["Materials<br/>material controller"]
  node_profile_ctrl["Profile"]
end

subgraph group_core["Core Domain"]
  node_domain["Domain model<br/>entities and enums"]
  node_user_service["Users<br/>user service<br/>[UserService.java]"]
  node_student_service["Students<br/>student service"]
  node_class_service["Classes<br/>class service<br/>[ClassService.java]"]
  node_grade_service["Grades<br/>grade service<br/>[GradeService.java]"]
  node_material_service["Materials<br/>material service"]
  node_repos[("Repositories<br/>data access")]
  node_mappers_dto["DTOs & Mappers<br/>view boundary"]
end

subgraph group_infra["Infrastructure"]
  node_templates["Thymeleaf UI<br/>server-rendered views"]
  node_static_assets["Static assets<br/>css/js/pdf assets"]
  node_uploads[("Uploads<br/>file storage")]
end

node_bootstrap -->|"loads"| node_config
node_bootstrap -->|"enables"| node_security
node_config -->|"configures"| node_templates
node_security -->|"protects"| node_controllers
node_controllers -->|"includes"| node_student_ctrl
node_controllers -->|"includes"| node_class_ctrl
node_controllers -->|"includes"| node_grade_ctrl
node_controllers -->|"includes"| node_material_ctrl
node_controllers -->|"includes"| node_profile_ctrl
node_student_ctrl -->|"uses"| node_student_service
node_class_ctrl -->|"uses"| node_class_service
node_grade_ctrl -->|"uses"| node_grade_service
node_material_ctrl -->|"uses"| node_material_service
node_profile_ctrl -->|"uses"| node_user_service
node_user_service -->|"reads/writes"| node_domain
node_student_service -->|"persists via"| node_repos
node_class_service -->|"persists via"| node_repos
node_grade_service -->|"persists via"| node_repos
node_material_service -->|"persists via"| node_repos
node_user_service -->|"persists via"| node_repos
node_controllers -->|"transforms"| node_mappers_dto
node_student_service -->|"transforms"| node_mappers_dto
node_class_service -->|"transforms"| node_mappers_dto
node_grade_service -->|"transforms"| node_mappers_dto
node_material_service -->|"transforms"| node_mappers_dto
node_templates -->|"includes"| node_static_assets
node_material_service -->|"stores files"| node_uploads

click node_bootstrap "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/ElmsApplication.java"
click node_config "https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/config"
click node_security "https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/Security"
click node_controllers "https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/controller"
click node_student_ctrl "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/StudentController.java"
click node_class_ctrl "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/ClassController.java"
click node_grade_ctrl "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/GradeController.java"
click node_material_ctrl "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/MaterialController.java"
click node_profile_ctrl "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/ProfileController.java"
click node_templates "https://github.com/megadiiiii/elms/tree/main/src/main/resources/templates"
click node_domain "https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/models"
click node_user_service "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/UserService.java"
click node_student_service "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/StudentService.java"
click node_class_service "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/ClassService.java"
click node_grade_service "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/GradeService.java"
click node_material_service "https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/MaterialService.java"
click node_repos "https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/repository"
click node_mappers_dto "https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/dto"
click node_static_assets "https://github.com/megadiiiii/elms/tree/main/src/main/resources/static"
click node_uploads "https://github.com/megadiiiii/elms/tree/main/uploads/avatars"

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_bootstrap,node_config,node_security toneBlue
class node_controllers,node_student_ctrl,node_class_ctrl,node_grade_ctrl,node_material_ctrl,node_profile_ctrl toneAmber
class node_domain,node_user_service,node_student_service,node_class_service,node_grade_service,node_material_service,node_repos,node_mappers_dto toneMint
class node_templates,node_static_assets,node_uploads toneRose
```

## Components

### Application

Bootstrapping and cross-cutting configuration

- [ELMS app](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/ElmsApplication.java): Spring Boot entrypoint · Main application bootstrap · `src/main/java/com/megadiiiii/elms/ElmsApplication.java`
- [Config](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/config): web/data config · MVC, Thymeleaf, startup data, and password setup · `src/main/java/com/megadiiiii/elms/config`
- [Security](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/Security): auth boundary · Spring Security configuration and login failure handling · `src/main/java/com/megadiiiii/elms/Security`

### Web Layer

Controllers and server-rendered UI

- [Controllers](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/controller): MVC controllers · Browser-facing request handlers for each feature area · `src/main/java/com/megadiiiii/elms/controller`
- [Student](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/StudentController.java): student controller · Student pages and forms · `src/main/java/com/megadiiiii/elms/controller/StudentController.java`
- [Class](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/ClassController.java): class controller · Class, session, and attendance views · `src/main/java/com/megadiiiii/elms/controller/ClassController.java`
- [Grades](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/GradeController.java): grade controller · Grade input and view pages · `src/main/java/com/megadiiiii/elms/controller/GradeController.java`
- [Materials](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/MaterialController.java): material controller · Lesson material management and preview · `src/main/java/com/megadiiiii/elms/controller/MaterialController.java`
- [Profile](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/controller/ProfileController.java): profile controller · Self-service profile pages · `src/main/java/com/megadiiiii/elms/controller/ProfileController.java`

### Core Domain

Services, DTOs, mapping, and persistence

- [Domain model](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/models): entities and enums · Users, academic structure, attendance, grades, and materials · `src/main/java/com/megadiiiii/elms/models`
- [Users](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/UserService.java): user service · Account, identity, and security-related user logic · `src/main/java/com/megadiiiii/elms/services/UserService.java`
- [Students](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/StudentService.java): student service · Student lifecycle and profile logic · `src/main/java/com/megadiiiii/elms/services/StudentService.java`
- [Classes](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/ClassService.java): class service · Class and session orchestration · `src/main/java/com/megadiiiii/elms/services/ClassService.java`
- [Grades](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/GradeService.java): grade service · Grade calculation and persistence workflows · `src/main/java/com/megadiiiii/elms/services/GradeService.java`
- [Materials](https://github.com/megadiiiii/elms/blob/main/src/main/java/com/megadiiiii/elms/services/MaterialService.java): material service · Lesson material management and file handling · `src/main/java/com/megadiiiii/elms/services/MaterialService.java`
- [Repositories](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/repository): data access · Spring Data repositories for master and operational records · `src/main/java/com/megadiiiii/elms/repository`
- [DTOs & Mappers](https://github.com/megadiiiii/elms/tree/main/src/main/java/com/megadiiiii/elms/dto): view boundary · Form DTOs, response DTOs, and entity-to-view mapping · `src/main/java/com/megadiiiii/elms/dto`

### Infrastructure

Templates, static assets, and file storage

- [Thymeleaf UI](https://github.com/megadiiiii/elms/tree/main/src/main/resources/templates): server-rendered views · Page templates, layouts, and shared fragments · `src/main/resources/templates`
- [Static assets](https://github.com/megadiiiii/elms/tree/main/src/main/resources/static): css/js/pdf assets · Browser-side styling, scripts, and PDF viewer support · `src/main/resources/static`
- [Uploads](https://github.com/megadiiiii/elms/tree/main/uploads/avatars): file storage · Filesystem boundary for avatars and uploaded files · `uploads/avatars`

## Connections

- ELMS app → Config: loads · Application startup wires configuration
- ELMS app → Security: enables · Bootstraps the security boundary
- Config → Thymeleaf UI: configures · Sets up Thymeleaf and web rendering
- Security → Controllers: protects · Secures browser-facing request handling
- Controllers → Student: includes · Feature-specific student requests
- Controllers → Class: includes · Feature-specific class and attendance requests
- Controllers → Grades: includes · Feature-specific grade requests
- Controllers → Materials: includes · Feature-specific material requests
- Controllers → Profile: includes · Feature-specific profile requests
- Student → Students: uses · Delegates student workflows to services
- Class → Classes: uses · Delegates class workflows to services
- Grades → Grades: uses · Delegates grading workflows to services
- Materials → Materials: uses · Delegates material workflows to services
- Profile → Users: uses · Delegates profile and account updates
- Users → Domain model: reads/writes · Operates on user and role entities
- Students → Repositories: persists via · Reads and writes student-related data
- Classes → Repositories: persists via · Reads and writes class and schedule data
- Grades → Repositories: persists via · Reads and writes grade data
- Materials → Repositories: persists via · Reads and writes lesson material data
- Users → Repositories: persists via · Reads and writes user and role data
- Controllers → DTOs & Mappers: transforms · Maps between forms, view models, and entities
- Students → DTOs & Mappers: transforms · Uses DTOs and mappers for student views
- Classes → DTOs & Mappers: transforms · Uses DTOs and mappers for class views
- Grades → DTOs & Mappers: transforms · Uses DTOs and mappers for grade views
- Materials → DTOs & Mappers: transforms · Uses DTOs and mappers for material views
- Thymeleaf UI → Static assets: includes · UI pages rely on shared static resources
- Materials → Uploads: stores files · Material and avatar uploads land on disk