# jhonatademuner/studai architecture

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

- Interactive diagram: https://gitdiagram.com/jhonatademuner/studai
- Repository: https://github.com/jhonatademuner/studai

## Overview

##### Project type and purpose
- This is a standalone **backend microservice** (Spring Boot) that exposes REST APIs for the StudAI quiz platform. It handles user management, question/quiz persistence, authentication (JWT + Spring Security), and delegates quiz‐generation to an external “studai-assistant” microservice.

##### File structure
- Top-level layers correspond to:
- client (HTTP client for studai-assistant)
- config (CORS, Security, RestTemplate)
- controller (REST API endpoints)
- service (business logic + JWT management)
- repository (Spring Data JPA for PostgreSQL)
- domain (entities, enums, DTOs)
- utils (assemblers, exception handling)
- Database migrations live under `src/main/resources/db/migration` (SQL scripts).
- Build and CI/CD: Maven (`pom.xml`, Maven wrapper) and GitHub Actions workflow (`.github/workflows/java-backend-ci-cd.yml`).

##### README for additional insights
- Uses PostgreSQL (Docker) for data persistence.
- Integrates with `studai-assistant` microservice via REST (configured by `AssistantProperties` + `AssistantClient`).
- Exposes Swagger UI at `/swagger-ui/index.html` for API exploration.
- Enforces JWT-based authentication via a `JWTFilter` and `SecurityConfig`.

##### Main components & interactions (to include
a. External Client (Web or Mobile)
- Issues HTTPS requests →
b. API Gateway / Spring Boot Application
- **CORSConfig**
- **JWTFilter** / **SecurityConfig**
- **Controllers** (UserController, QuestionController, QuizController)
- **Services** (UserService, QuestionService, QuizService, JWTService)
- **AssistantClient** (RestTemplate adapter to studai-assistant)
- **Exception Handling** (GlobalExceptionHandler)
c. Database (PostgreSQL)
- Entities managed by JPA Repositories (UserRepository, QuestionRepository, QuizRepository, QuizAttemptRepository)
- Schema evolution via migration scripts
d. External Service: studai-assistant
- Hosts AI quiz‐generation logic
- Invoked by `QuizService` through `AssistantClient`

##### Architectural patterns & design principles
- **Layered (Onion / Hexagonal)**: Controllers → Services → Repositories → Database
- **Separation of Concerns**: DTOs + Assemblers decouple domain models from API contracts
- **External API Client (Adapter Pattern)**: `AssistantClient` isolates remote‐service calls
- **Security Filter Chain**: JWT filter sits before controller invocation
- **Database Migrations**: Immutable SQL scripts for versioned schema changes

##### Essential elements
- Clear component names (e.g., QuizController, QuizService, QuizRepository)
- Annotations for critical configurations (CORS, JWT) and migration path

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Client
    ExternalClient["External Client\n(Web/Mobile)"]:::external

    %% Spring Boot Application
    subgraph "Spring Boot Application" 
        direction TB

        %% Config Layer
        subgraph "Config Layer"
            direction TB
            CorsConfig["CorsConfig"]:::config
            SecurityConfig["SecurityConfig"]:::config
            RestTemplateConfig["RestTemplateConfig"]:::config
            JWTFilter["JWTFilter"]:::config
        end

        %% Controller Layer
        subgraph "Controller Layer"
            direction TB
            UserController["UserController"]:::controller
            QuestionController["QuestionController"]:::controller
            QuizController["QuizController"]:::controller
            SwaggerUI["Swagger UI\n(/swagger-ui/index.html)"]:::controller
        end

        %% Service Layer
        subgraph "Service Layer"
            direction TB
            UserService["UserService"]:::service
            StudaiUserDetailsService["StudaiUserDetailsService"]:::service
            QuestionService["QuestionService"]:::service
            QuizService["QuizService"]:::service
            JWTService["JWTService"]:::service
        end

        %% Assistant Client
        AssistantClient["AssistantClient"]:::service

        %% Repository Layer
        subgraph "Repository Layer"
            direction TB
            UserRepository["UserRepository"]:::repository
            QuestionRepository["QuestionRepository"]:::repository
            QuizRepository["QuizRepository"]:::repository
            QuizAttemptRepository["QuizAttemptRepository"]:::repository
        end

        %% Utils Layer
        subgraph "Utils Layer"
            direction TB
            GlobalExceptionHandler["GlobalExceptionHandler"]:::utils
            Assemblers["DTO Assemblers"]:::utils
        end
    end

    %% External Systems
    PostgreSQL["PostgreSQL Database"]:::external
    StudAIService["studai-assistant Service"]:::external
    Migrations["DB Migrations\n(src/main/resources/db/migration)"]:::external

    %% Connections
    ExternalClient -->|"JSON/HTTP"| CorsConfig
    CorsConfig --> SecurityConfig
    SecurityConfig --> JWTFilter
    JWTFilter --> UserController
    JWTFilter --> QuestionController
    JWTFilter --> QuizController

    UserController -->|"calls"| UserService
    QuestionController -->|"calls"| QuestionService
    QuizController -->|"calls"| QuizService
    SwaggerUI --> UserController

    UserService --> StudaiUserDetailsService
    UserService --> UserRepository
    StudaiUserDetailsService --> UserRepository
    QuestionService --> QuestionRepository
    QuizService --> QuizRepository
    QuizService --> QuizAttemptRepository
    QuizService --> AssistantClient
    JWTService --> JWTFilter

    AssistantClient -->|"REST/HTTP"| StudAIService

    UserRepository -->|"JPA"| PostgreSQL
    QuestionRepository -->|"JPA"| PostgreSQL
    QuizRepository -->|"JPA"| PostgreSQL
    QuizAttemptRepository -->|"JPA"| PostgreSQL

    Migrations -->|"Flyway"| PostgreSQL

    GlobalExceptionHandler --> UserController
    GlobalExceptionHandler --> QuestionController
    GlobalExceptionHandler --> QuizController
    Assemblers --> UserService
    Assemblers --> QuestionService
    Assemblers --> QuizService

    %% Click Events
    click StudaiApplication.java "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/StudaiApplication.java"
    click CorsConfig "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/config/CorsConfig.java"
    click SecurityConfig "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/config/SecurityConfig.java"
    click RestTemplateConfig "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/config/RestTemplateConfig.java"
    click JWTFilter "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/config/filter/JWTFilter.java"
    click AssistantProperties "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/client/assistant/config/AssistantProperties.java"
    click AssistantClient "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/client/assistant/AssistantClient.java"
    click UserController "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/controller/user/UserController.java"
    click QuestionController "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/controller/question/QuestionController.java"
    click QuizController "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/controller/quiz/QuizController.java"
    click UserService "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/service/user/UserService.java"
    click StudaiUserDetailsService "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/service/user/StudaiUserDetailsService.java"
    click QuestionService "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/service/question/QuestionService.java"
    click QuizService "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/service/quiz/QuizService.java"
    click JWTService "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/service/jwt/JWTService.java"
    click UserRepository "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/repository/user/UserRepository.java"
    click QuestionRepository "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/repository/question/QuestionRepository.java"
    click QuizRepository "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/repository/quiz/QuizRepository.java"
    click QuizAttemptRepository "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/repository/quiz/attempt/QuizAttemptRepository.java"
    click Assemblers "https://github.com/jhonatademuner/studai/tree/main/src/main/java/com/studai/utils/assembler"
    click GlobalExceptionHandler "https://github.com/jhonatademuner/studai/blob/main/src/main/java/com/studai/utils/exception/GlobalExceptionHandler.java"
    click Migrations "https://github.com/jhonatademuner/studai/tree/main/src/main/resources/db/migration"
    click java-backend-ci-cd.yml "https://github.com/jhonatademuner/studai/blob/main/.github/workflows/java-backend-ci-cd.yml"
    click pom.xml "https://github.com/jhonatademuner/studai/blob/main/pom.xml"

    %% Styles
    classDef controller fill:#FFA500,stroke:#333,stroke-width:1px
    classDef service fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef repository fill:#90EE90,stroke:#333,stroke-width:1px
    classDef config fill:#DDA0DD,stroke:#333,stroke-width:1px
    classDef utils fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
