# niwas-kumar/ai-learning-disorder architecture

> Architecture diagram of the GitHub repository niwas-kumar/ai-learning-disorder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/niwas-kumar/ai-learning-disorder
- Repository: https://github.com/niwas-kumar/ai-learning-disorder

## Overview

##### Project type and purpose
- This is a Spring Boot 3.x REST-API backend (Java 17) for early detection of learning disorders in students.
- Teachers register students, record quizzes and handwriting samples, and review AI-based risk predictions.

##### File structure
Top-level within `ai-learning-disorder/`
- pom.xml, Maven wrapper & `.mvn/`: Maven build system
- `src/main/java/com/learningdetector/aild/`
– controller/: REST endpoints (QuestionController, QuizController, StudentController, TeacherController)
– dto/: request/response payloads
– entity/: JPA entities (Student, Teacher, Quiz, Question, QuizAttempt, Prediction)
– helpers/: utility classes (ExcelHelper for batch imports)
– repositories/: Spring Data JPA repositories (DAO layer)
– AiLearningDisorderApplication.java: Spring Boot main class
- `src/main/resources/application.properties`: DB configuration
- test/: basic Spring Boot startup test

##### README for additional insights
- Tech stack: Spring Boot + Spring Data JPA + Hibernate + MySQL
- No current service layer, but controllers encapsulate both routing and business logic
- Future: Python-based ML integration, JWT authentication, frontend dashboard

a. Main components
1. API Layer: Spring Boot application
- Controllers (REST endpoints)
- DTOs (payload definitions)
2. Business Logic Layer (implicit)
3. Data Access Layer
- Spring Data JPA repositories
4. Persistence
- MySQL database
- Entities mapped via Hibernate
5. Utilities
- ExcelHelper for quiz import
6. (Future) AI/ML Service
- Python microservice for risk prediction
7. (Future) Authentication Service
- JWT provider
8. (Future) Frontend
- React/Angular/Thymeleaf dashboard

b. Relationships and interactions
- Client → HTTP → Controllers
- Controllers → DTO mapping → Entities / Helpers
- Controllers → Repositories → MySQL
- ExcelHelper invoked by controllers to parse/upload spreadsheets → Entities → Repositories
- (Future) Controllers → REST call → ML Service → Prediction DTO → Persistence
- (Future) Frontend → consumes API endpoints (students, teachers, quizzes, predictions)

c. Architectural patterns / design principles
- Layered (Controller → Service/Helpers → Repository → DB)
- Convention-over-configuration (Spring Boot auto-wiring)
- DTOs to decouple API from persistence
- Repository pattern (Spring Data JPA)
- Utility component for file processing (ExcelHelper)

d. Key technologies/frameworks
- Spring Boot (REST API, dependency injection)
- Spring Data JPA + Hibernate (ORM)
- MySQL (relational DB)
- Lombok (entity/DTO boilerplate)
- Maven (build)
- Future: Python Flask/FastAPI (ML), JWT library, React/Angular

## Diagram (Mermaid)

```mermaid
flowchart TB
    classDef controller fill:#d5f5e3,stroke:#27ae60;
    classDef dto fill:#e8f8f5,stroke:#1abc9c;
    classDef helper fill:#fef9e7,stroke:#f1c40f;
    classDef repo fill:#ebdef0,stroke:#8e44ad;
    classDef entity fill:#f9ebea,stroke:#c0392b;
    classDef db fill:#d6eaf8,stroke:#2980b9,shape:cylinder;
    classDef externalService fill:#fdebd0,stroke:#e67e22,stroke-dasharray: 5 5;
    classDef client fill:#f5eef8,stroke:#9b59b6;
    classDef core fill:#e8e8e8,stroke:#7f8c8d;

    Browser["Frontend Client"]:::client

    Application["AiLearningDisorderApplication"]:::core
    Config["application.properties"]:::core

    subgraph "Controller Layer"
        StudentController["StudentController"]:::controller
        QuestionController["QuestionController"]:::controller
        QuizController["QuizController"]:::controller
        TeacherController["TeacherController"]:::controller
    end

    subgraph "DTOs"
        QuestionDTO["QuestionDTO"]:::dto
        QuizDTO["QuizDTO"]:::dto
        StudentDto["StudentDto"]:::dto
    end

    subgraph "Business Logic / Helpers"
        ExcelHelper["ExcelHelper"]:::helper
    end

    subgraph "Repository Layer"
        RepoGroup["Repositories"]:::repo
        QuestionRepository["QuestionRepository"]:::repo
        QuizRepository["QuizRepository"]:::repo
        StudentRepository["StudentRepository"]:::repo
    end

    subgraph "Entities"
        QuestionEntity["Question (Entity)"]:::entity
        QuizEntity["Quiz (Entity)"]:::entity
        QuizAttemptEntity["QuizAttempt (Entity)"]:::entity
        PredictionEntity["Prediction (Entity)"]:::entity
        StudentEntity["Student (Entity)"]:::entity
        TeacherEntity["Teacher (Entity)"]:::entity
    end

    MySQL["MySQL Database"]:::db

    ExternalML["External ML Service"]:::externalService
    AuthService["Auth Service (JWT)"]:::externalService

    Browser -->|"HTTP requests"| StudentController
    Browser --> QuestionController
    Browser --> QuizController
    Browser --> TeacherController

    StudentController --> DTOs
    QuestionController --> DTOs
    QuizController --> DTOs
    TeacherController --> DTOs

    StudentController --> ExcelHelper
    QuestionController --> ExcelHelper
    QuizController --> ExcelHelper

    ExcelHelper --> RepoGroup

    StudentController --> RepoGroup
    QuestionController --> RepoGroup
    QuizController --> RepoGroup
    TeacherController --> RepoGroup

    RepoGroup --> QuestionEntity
    RepoGroup --> QuizEntity
    RepoGroup --> QuizAttemptEntity
    RepoGroup --> PredictionEntity
    RepoGroup --> StudentEntity
    RepoGroup --> TeacherEntity

    RepoGroup --> MySQL

    StudentController -.-> ExternalML
    ExternalML --> PredictionEntity
    ExternalML -.-> MySQL

    AuthService -.-> StudentController
    AuthService -.-> QuestionController
    AuthService -.-> QuizController
    AuthService -.-> TeacherController

    %% Click Events
    click Browser "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/resources/application.properties"
    click Application "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/AiLearningDisorderApplication.java"
    click Config "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/resources/application.properties"
    click StudentController "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/controllers/StudentController.java"
    click QuestionController "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/controllers/QuestionController.java"
    click QuizController "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/controllers/QuizController.java"
    click TeacherController "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/controllers/TeacherController.java"
    click QuestionDTO "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/dto/QuestionDTO.java"
    click QuizDTO "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/dto/QuizDTO.java"
    click StudentDto "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/dto/StudentDto.java"
    click ExcelHelper "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/helpers/ExcelHelper.java"
    click RepoGroup "https://github.com/niwas-kumar/ai-learning-disorder/tree/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/repositories"
    click QuestionRepository "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/repositories/QuestionRepository.java"
    click QuizRepository "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/repositories/QuizRepository.java"
    click StudentRepository "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/repositories/StudentRepository.java"
    click PredictionEntity "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/entity/Prediction.java"
    click QuestionEntity "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/entity/Question.java"
    click QuizEntity "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/entity/Quiz.java"
    click QuizAttemptEntity "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/entity/QuizAttempt.java"
    click StudentEntity "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/entity/Student.java"
    click TeacherEntity "https://github.com/niwas-kumar/ai-learning-disorder/blob/main/ai-learning-disorder/src/main/java/com/learningdetector/aild/entity/Teacher.java"
```
