# luiiscarlos/academ-iq-api architecture

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

- Interactive diagram: https://gitdiagram.com/luiiscarlos/academ-iq-api
- Repository: https://github.com/luiiscarlos/academ-iq-api

## Overview

##### Project Type and Purpose
- This is a standalone Spring Boot backend (“Academ IQ API”) that exposes a RESTful API for an educational platform.
- It’s a monolithic, layered service providing user authentication/authorization, course management, enrollments, progress tracking, file storage, and email notifications.

##### Key Architectural Patterns
- Layered (onion) architecture:
- Controllers (REST endpoints)
- Services (business logic)
- Repositories (data access via Spring Data JPA)
- Models/Entities (JPA) and DTOs
- Security via JWT tokens and servlet filters (filter chain pattern).
- Exception handling via a global exception handler.

##### Main Components
A. Externals & Clients
- API Clients (Web/Mobile)
- SMTP/Email Service (MailService)
- File storage (local FS or cloud bucket)
- Database (e.g., MySQL/PostgreSQL)
B. API Application (containerized via Docker/Fly.io)
1. Security Layer
– AccessTokenFilter
– ExceptionHandlingFilter
– SecurityConfiguration (HttpSecurity rules)
2. Controllers Layer
– AuthController, UserController, CourseController, EnrollmentController, FileController, RatingController, AdminController
3. Services Layer
– AuthServiceImpl, UserServiceImpl, CourseService, EnrollmentService, FileServiceImpl, RatingService, TokenServiceImpl, MailService, RoleService
4. Persistence Layer
– Repositories: UserRepository, CourseRepository, EnrollmentRepository, FileRepository, RatingRepository, etc.
– Entities and DTOs (models, mappers)
5. Utilities & Config
– RSAKeyProperties & KeyGeneratorUtility (JWT keypair)
– ErrorHandler, UtilConfiguration

##### Interactions & Data Flows
- Client → HTTP request → Security Filter Chain → Controller → Service → Repository → Database → back up the stack → HTTP response → Client
- Service → MailService → External SMTP
- FileController → FileService → Local/Cloud storage
- TokenService → RSA keys → JWT generation/validation

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External entities
    Clients(["API Clients (Web/Mobile)"]):::external
    SMTP(["SMTP / Email Service"]):::external
    FileStorage(["File Storage (Local FS / Cloud)"]):::storage
    DB(["Database (MySQL/PostgreSQL)"]):::database

    %% Main container
    subgraph "Academ IQ API (Docker/Fly.io)" 
        direction TB

        %% Security Layer
        subgraph "Security Layer"
            direction TB
            ATF["AccessTokenFilter"]:::security
            EHF["ExceptionHandlingFilter"]:::security
            SC["SecurityConfiguration"]:::security
            AC["AuthConfiguration"]:::security
        end

        %% Controllers Layer
        subgraph "Controllers"
            direction TB
            AuthC["AuthController"]:::controller
            UserC["UserController"]:::controller
            CourseC["CourseController"]:::controller
            EnrollC["EnrollmentController"]:::controller
            FileC["FileController"]:::controller
            RatingC["RatingController"]:::controller
            AdminC["AdminController"]:::controller
        end

        %% Services Layer
        subgraph "Services"
            direction TB
            AuthS["AuthServiceImpl"]:::service
            UserS["UserServiceImpl"]:::service
            CourseS["CourseService"]:::service
            EnrollS["EnrollmentService"]:::service
            FileS["FileServiceImpl"]:::service
            RatingS["RatingService"]:::service
            TokenS["TokenServiceImpl"]:::service
            MailS["MailService"]:::service
            RoleS["RoleService"]:::service
        end

        %% Persistence Layer
        subgraph "Repositories"
            direction TB
            UserR["UserRepository"]:::repository
            CourseR["CourseRepository"]:::repository
            EnrollR["EnrollmentRepository"]:::repository
            FileR["FileRepository"]:::repository
            RatingR["RatingRepository"]:::repository
            RefreshR["RefreshTokenRepository"]:::repository
            RoleR["RoleRepository"]:::repository
            CategoryR["CategoryRepository"]:::repository
        end

        %% Utilities & Config
        subgraph "Utils & Config"
            direction TB
            RSAProps["RSAKeyProperties"]:::config
            KeyGen["KeyGeneratorUtility"]:::config
            ErrorH["ErrorHandler"]:::config
            UtilCfg["UtilConfiguration"]:::config
            GlobalEx["GlobalExceptionHandler"]:::config
        end
    end

    %% Connections: HTTP flow
    Clients -->|"HTTP Request"| ATF
    ATF -->|forward| EHF
    EHF -->|security rules| SC
    SC --> AC
    AC -->|to controllers| AuthC
    AuthC --> UserC
    UserC --> CourseC
    CourseC --> EnrollC
    EnrollC --> FileC
    FileC --> RatingC
    RatingC --> AdminC

    %% Controllers to Services
    AuthC -->AuthS
    UserC -->UserS
    CourseC -->CourseS
    EnrollC -->EnrollS
    FileC -->FileS
    RatingC -->RatingS
    AdminC -->MailS

    %% Services to Repositories
    AuthS -->UserR
    UserS -->UserR
    CourseS -->CourseR
    EnrollS -->EnrollR
    FileS -->FileR
    RatingS -->RatingR
    TokenS -->RefreshR
    RoleS -->RoleR
    CourseS -->CategoryR

    %% Services to externals
    MailS -->|send email| SMTP
    FileS -->|store files| FileStorage

    %% Repositories to DB
    UserR -->|JPA| DB
    CourseR -->|JPA| DB
    EnrollR -->|JPA| DB
    FileR -->|JPA| DB
    RatingR -->|JPA| DB
    RefreshR -->|JPA| DB
    RoleR -->|JPA| DB
    CategoryR -->|JPA| DB

    %% Utils & Config attachments
    RSAProps --> TokenS
    KeyGen --> TokenS
    ErrorH --> EHF
    UtilCfg --> SC
    GlobalEx --> EHF

    %% Return flow
    DB -->|data| Repositories
    Repositories --> Services
    Services --> Controllers
    Controllers -->|HTTP Response| Clients

    %% Click events
    click ATF "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/config/filters/AccessTokenFilter.java"
    click EHF "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/config/filters/ExceptionHandlingFilter.java"
    click SC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/config/SecurityConfiguration.java"
    click AC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/config/AuthConfiguration.java"
    click AuthC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/controllers/AuthController.java"
    click UserC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/controllers/UserController.java"
    click CourseC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/controllers/CourseController.java"
    click EnrollC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/controllers/EnrollmentController.java"
    click FileC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/controllers/FileController.java"
    click RatingC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/controllers/RatingControlller.java"
    click AdminC "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/controllers/AdminController.java"
    click AuthS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/AuthServiceImpl.java"
    click UserS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/UserServiceImpl.java"
    click CourseS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/CourseService.java"
    click EnrollS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/EnrollmentService.java"
    click FileS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/FileServiceImpl.java"
    click RatingS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/RatingService.java"
    click TokenS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/TokenServiceImpl.java"
    click MailS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/MailService.java"
    click RoleS "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/services/RoleService.java"
    click UserR "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/repositories/UserRepository.java"
    click CourseR "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/repositories/CourseRepository.java"
    click EnrollR "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/repositories/EnrollmentRepository.java"
    click FileR "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/repositories/FileRepository.java"
    click RatingR "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/repositories/RatingRepository.java"
    click RefreshR "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/repositories/RefreshTokenRepository.java"
    click RoleR "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/repositories/RoleRepository.java"
    click CategoryR "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/repositories/CategoryRepository.java"
    click RSAProps "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/utils/RSAKeyProperties.java"
    click KeyGen "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/utils/KeyGeneratorUtility.java"
    click ErrorH "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/utils/ErrorHandler.java"
    click UtilCfg "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/config/UtilConfiguration.java"
    click GlobalEx "https://github.com/luiiscarlos/academ-iq-api/blob/main/src/main/java/dev/luiiscarlos/academ_iq_api/exceptions/handlers/GlobalExceptionHandler.java"

    %% Styles
    classDef external fill:#EEEEEE,stroke:#888888,stroke-width:1px;
    classDef security fill:#FFD6D6,stroke:#FF5555,stroke-width:1px;
    classDef controller fill:#D6E4FF,stroke:#3366FF,stroke-width:1px;
    classDef service fill:#FFE9CC,stroke:#FF9933,stroke-width:1px;
    classDef repository fill:#D6FFD6,stroke:#33AA33,stroke-width:1px;
    classDef config fill:#FFF0B3,stroke:#CC9900,stroke-width:1px;
    classDef database fill:#FFEEFF,stroke:#CC33CC,stroke-width:1px;
    classDef storage fill:#E8E8FF,stroke:#6666FF,stroke-width:1px;
```
