# elesquina/pixellms architecture

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

- Interactive diagram: https://gitdiagram.com/elesquina/pixellms
- Repository: https://github.com/elesquina/pixellms

## Overview

##### Project type and purpose
- Pixel LMS is a full-stack web application (Learning Management System).
- Frontend: Single Page Application built with Vue.js.
- Backend: RESTful API server built with Spring Boot (Java).
- Database: Relational database managed via raw SQL (PostgreSQL or similar).
- Purpose: Manage courses, assignments, events, discussions, and role-based user access in an academic setting.

##### File structure
- Top-level directories:
- pixel_frontend/ – Vue.js application (components, views, router, plugins, assets).
- pixel_backend/ – Spring Boot application (controllers, models, repositories, security, utilities).
- sql/ – DDL scripts, stored procedures, transactions.
- dummy data/ – Test data generation notebooks and CSV files.
- Configuration files:
- application.properties in backend for DB and security settings.
- vue.config.js, babel.config.js, package.json in frontend.
- Build scripts:
- Maven wrapper (mvnw) for backend.
- npm scripts for frontend.

##### Read README for architecture and patterns
- MVC pattern: Controllers (REST layer), Models (domain objects), Views (Vue components).
- Design patterns:
- Factory (hashing algorithms)
- Strategy (row mapping)
- Command (permission checks)
- GlobalExceptionHandler (ControllerAdvice)
- Security: Bearer tokens, role-based permissions, interceptors.

##### Main components
a. Frontend SPA (Vue.js)
- Pages/Views (Login, Dashboard, Course Views, Admin Panels)
- API client module handling HTTP requests and token management
b. Backend REST API (Spring Boot)
- Controllers (AuthController, CourseController, TaskController, etc.)
- Security layer (TokenInterceptor, PermissionChecker, CommandRegistry)
- Service/Utility components (AuthHandler, FileStorageManager)
- Repository layer (DAO using raw SQL and RowMapperStrategy)
- GlobalExceptionHandler
c. Database
- Tables: user, course, task, calendar, discussion, message, file, etc.
- Stored procedures and transactional scripts
d. File storage
- Local filesystem or cloud bucket managed by FileStorageManager
e. External tools (for testing & data)
- Postman for API testing
- Python notebook for dummy-data generation

##### Relationships and interactions
- Frontend ↔ Backend: REST calls over HTTPS, Bearer token in Authorization header.
- Backend Security:
- On each request, TokenInterceptor validates token via TokenRegistry.
- PermissionChecker and CommandRegistry enforce RBAC per endpoint.
- Backend ↔ Database:
- Controllers delegate to repository layer, which executes raw SQL queries.
- RowMapperStrategy maps result sets into Java model objects.
- Backend ↔ File Storage:
- FileController uses FileStorageManager to save/retrieve files.
- Transactional boundaries:
- @Transactional on service methods coordinate multi-step operations (e.g., course creation).

##### Architectural patterns
- Layered MVC: separates presentation, business logic, data access.
- Command Pattern: encapsulates permission checks per action.
- Strategy Pattern: pluggable row mapping strategies.
- Factory Pattern: dynamic selection of hashing algorithm.
- Global Exception Handling: centralized error responses.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend SPA" 
        direction TB
        FE_Main["Entry Point\nmain.js"]:::frontend
        FE_Config["vue.config.js"]:::frontend
        FE_Router["Router\nindex.js"]:::frontend
        FE_Views["Views (Pages)"]:::frontend
        FE_Components["UI Components"]:::frontend
        FE_APIClient["API Client\napiUtils.js\nauth.js"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend REST API" 
        direction TB
        BE_Entry["Spring Boot\nBackendApplication.java"]:::backend

        subgraph "Controllers" 
            direction TB
            AuthController["AuthController"]:::backend
            CourseController["CourseController"]:::backend
            TaskController["TaskController"]:::backend
            GlobalExceptionHandler["GlobalExceptionHandler"]:::backend
        end

        subgraph "Security Layer" 
            direction TB
            TokenInterceptor["TokenInterceptor"]:::backend
            WebConfig["WebConfig"]:::backend
            TokenRegistry["TokenRegistry"]:::backend
            PermissionChecker["PermissionChecker"]:::backend
            CommandRegistry["CommandRegistry"]:::backend
            PermissionCommands["Permission Commands"]:::backend
            HashFactory["Hasher Factory"]:::backend
        end

        subgraph "Services & Utilities" 
            direction TB
            AuthHandler["AuthHandler"]:::backend
            FileStorageManager["FileStorageManager"]:::backend
        end

        subgraph "Repository Layer" 
            direction TB
            DAOs["DAO Repositories"]:::backend
            RowMapperStrategy["RowMapper Strategy"]:::backend
        end
    end

    %% External Systems
    Database[(Database)]:::external
    FileStorage[(File Storage)]:::external

    subgraph "DB Scripts" 
        direction TB
        DDL["database-DDL.sql"]:::external
        StoredProc["database-storedproc.sql"]:::external
        Transactions["database-transactions.sql"]:::external
    end

    subgraph "Dummy Data Tools"
        direction TB
        CSV["CSV Files"]:::external
        Notebook["Data Notebook\ndatapopulation.ipynb"]:::external
    end

    Postman["Postman"]:::external

    %% Connections
    User["User"]:::external -->|uses| FE_Main
    FE_Main --> FE_Router
    FE_Router --> FE_Views
    FE_Views --> FE_Components
    FE_Components --> FE_APIClient
    FE_APIClient -->|HTTPS JSON| AuthController
    FE_APIClient -->|HTTPS JSON| CourseController
    FE_APIClient -->|HTTPS JSON| TaskController

    AuthController --> TokenInterceptor
    CourseController --> TokenInterceptor
    TaskController --> TokenInterceptor

    TokenInterceptor --> TokenRegistry
    TokenInterceptor --> PermissionChecker
    PermissionChecker --> CommandRegistry
    CommandRegistry --> PermissionCommands
    TokenRegistry --> HashFactory

    ControllersSubgraph---ServicesSubgraph
    AuthController --> AuthHandler
    AuthController --> DAOs
    CourseController --> AuthHandler
    CourseController --> DAOs
    TaskController --> AuthHandler
    TaskController --> DAOs

    FileController["FileController"]:::backend
    FE_APIClient -->|file upload/download| FileController
    FileController --> FileStorageManager
    FileStorageManager --> FileStorage

    DAOs --> RowMapperStrategy
    DAOs --> Database
    Database --> DDL
    Database --> StoredProc
    Database --> Transactions

    Postman --> AuthController
    Notebook --> CSV

    %% Click Events Frontend
    click FE_Main "https://github.com/elesquina/pixellms/blob/main/pixel_frontend/src/main.js"
    click FE_Config "https://github.com/elesquina/pixellms/blob/main/pixel_frontend/vue.config.js"
    click FE_Router "https://github.com/elesquina/pixellms/blob/main/pixel_frontend/src/router/index.js"
    click FE_Views "https://github.com/elesquina/pixellms/tree/main/pixel_frontend/src/views/"
    click FE_Components "https://github.com/elesquina/pixellms/tree/main/pixel_frontend/src/components/"
    click FE_APIClient "https://github.com/elesquina/pixellms/blob/main/pixel_frontend/src/modules/apiUtils.js"
    click FE_APIClient "https://github.com/elesquina/pixellms/blob/main/pixel_frontend/src/modules/auth.js"
    click FE_Main "https://github.com/elesquina/pixellms/tree/main/pixel_frontend/"

    %% Click Events Backend
    click BE_Entry "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/BackendApplication.java"
    click AuthController "https://github.com/elesquina/pixellms/tree/main/pixel_backend/src/main/java/lms/pixel/backend/controller/"
    click GlobalExceptionHandler "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/Exceptions/GlobalExceptionHandler.java"
    click TokenInterceptor "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/config/TokenInterceptor.java"
    click WebConfig "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/config/WebConfig.java"
    click TokenRegistry "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/security/TokenRegistry.java"
    click PermissionChecker "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/security/PermissionChecker.java"
    click CommandRegistry "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/security/CommandRegistry.java"
    click PermissionCommands "https://github.com/elesquina/pixellms/tree/main/pixel_backend/src/main/java/lms/pixel/backend/security/permissionCommand/"
    click HashFactory "https://github.com/elesquina/pixellms/tree/main/pixel_backend/src/main/java/lms/pixel/backend/security/hasherFactory/"
    click DAOs "https://github.com/elesquina/pixellms/tree/main/pixel_backend/src/main/java/lms/pixel/backend/repository/"
    click RowMapperStrategy "https://github.com/elesquina/pixellms/tree/main/pixel_backend/src/main/java/lms/pixel/backend/rowMapperStrategy/"
    click AuthHandler "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/utils/AuthHandler.java"
    click FileStorageManager "https://github.com/elesquina/pixellms/blob/main/pixel_backend/src/main/java/lms/pixel/backend/utils/FileStorageManager.java"

    %% Click Events Database & Scripts
    click DDL "https://github.com/elesquina/pixellms/blob/main/sql/database-DDL.sql"
    click StoredProc "https://github.com/elesquina/pixellms/blob/main/sql/database-storedproc.sql"
    click Transactions "https://github.com/elesquina/pixellms/blob/main/sql/database-transactions.sql"

    %% Click Events Dummy Data
    click CSV "https://github.com/elesquina/pixellms/tree/main/dummy data/csv/"
    click Notebook "https://github.com/elesquina/pixellms/blob/main/dummy data/datapopulation.ipynb"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef backend fill:#DFFFE0,stroke:#228B22,color:#228B22;
    classDef external fill:#FFE8B0,stroke:#FF8C00,color:#FF8C00;
```
