# ssssssss-team/magic-api architecture

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

- Interactive diagram: https://gitdiagram.com/ssssssss-team/magic-api
- Repository: https://github.com/ssssssss-team/magic-api

## Overview

##### Project Type and Purpose
- This is a Java‑based, rapid HTTP API development framework that eliminates the need for manually writing controllers, services, DAOs, etc. It is designed to dynamically register APIs using configurations and embedded scripts (via the integrated magic‑script engine).
- The project is modular. It provides a core engine to handle API requests and several plugins that extend functionality (such as cluster management, document generation, integration with databases – both relational and non‑relational, caching, Git integration, Swagger/SpringDoc documentation, and more).
- There’s also a web‑based editor component (magic‑editor) that supplies a UI for writing and testing interfaces.

##### File Structure to Identify Key Architectural Components
- There are several top‑level modules:
- The core module (found under “magic‑api/src/”) contains the main engine logic, including API mapping, dynamic registry, request handling, configuration (security, pagination, caching), resource management, and even event and logging subsystems.
- The “magic‑api‑plugins” directory includes many submodules – for clustering, supporting various data sources (Elasticsearch, Mongo, Redis, Git), documentation (Swagger, SpringDoc), task scheduling and component management. Each plugin typically follows the standard Maven structure with resources and Java source packages.
- The servlet modules (“magic‑api‑servlet”) have separate implementations for different servlet environments (Jakarta vs. JavaEE), which help integrate the framework into various container environments.
- The “magic‑api‑spring‑boot‑starter” module provides the Spring Boot autoconfiguration, simplifying the integration of the framework into Spring Boot applications.
- The “magic‑editor” module provides the front‑end assets for the UI (HTML, CSS, JS, Vue.js components) enabling online editing and debugging.
- Common build files (pom.xml) and configuration files provide hints at how the modules interconnect.

##### Main Components
a. Core Engine:
- Responsible for processing API requests, managing API registration, handling dynamic script execution, and coordinating between resources.
- Includes subsystems like:
- Request Mapping and Controllers (e.g., MagicController, MagicResourceController)
- API Dynamic Registry, Resource Storage, and Event Handling
- Exception handling, logging, and configuration management (security, caching, etc.)
b. Plugin Modules:
- Each plugin (cluster, component, elasticsearch, git, mongo, redis, swagger, springdoc, task) should be drawn as a distinct component that plugs into the core engine. They add specific functionality and “auto-configuration” support via Spring’s autoconfiguration (spring.factories) files.
c. Servlet and Spring Boot Integration:
- Magic‑api‑servlet modules (Jakarta and JavaEE implementations) alongside the magic‑api‑spring‑boot‑starter module. These components illustrate how the framework integrates with the hosting environment (traditional servlet containers or Spring Boot applications).
d. Data and External Systems:
- External components or services such as JDBC databases, Redis, MongoDB, and any external API resources that the framework can connect to.
e. Magic‑Editor (Front‑end):
- Online UI editor as a separate front‑end module that interacts with the core engine’s API configuration/storage. Include a note on how it is a static asset server (with assets like JavaScript and CSS from “magic‑editor/src/main/resources/magic-editor/assets”) and how it interacts over HTTP.
f. Scripting Engine:
- (Optionally) Represent the integration of the magic‑script engine that allows for dynamic script execution without restarting the server.

##### Relationships and Data Flows
- That the Magic‑Editor sends configuration and test requests to the Core Engine.
- Core Engine with the various plugin modules (illustrate that plugins are “plugged into” the core through the Spring autoconfiguration mechanism).
- Demonstrate how the servlet and Spring Boot starter components expose HTTP endpoints to external clients.
- That the core engine interacts with external databases and services like Redis, MongoDB, and relational databases through designated data source components.

##### Architectural Patterns and Technologies
- That the framework follows a modular and plugin‑based architecture.
- That it leverages Spring Boot auto‑configuration, dependency injection, and (optionally) MVC patterns for handling HTTP requests.
- Technology labels like Java 8+, Maven (build tool), Spring Boot, and servlet specifications (Jakarta/JavaEE).
- Dynamic “magic‑script” for runtime API registration and execution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["User/Client"]:::external

    %% UI Layer
    subgraph "UI Layer"
        Editor["Magic Editor UI"]:::editor
    end

    %% Core Engine Components
    subgraph "Core Engine"
        Core["Core Engine"]:::core
        Script["Scripting Engine"]:::core
    end

    %% Plugin Ecosystem
    subgraph "Plugin Ecosystem"
        Cluster["Cluster Plugin"]:::plugin
        Component["Component Plugin"]:::plugin
        Elasticsearch["Elasticsearch Plugin"]:::plugin
        Git["Git Plugin"]:::plugin
        Mongo["Mongo Plugin"]:::plugin
        Redis["Redis Plugin"]:::plugin
        SpringDoc["SpringDoc Plugin"]:::plugin
        Swagger["Swagger Plugin"]:::plugin
        Task["Task Plugin"]:::plugin
    end

    %% Integration Modules
    subgraph "Integration"
        Jakarta["Servlet (Jakarta)"]:::integration
        JavaEE["Servlet (JavaEE)"]:::integration
        SpringBoot["Spring Boot Integration"]:::integration
    end

    %% External Systems
    subgraph "External Systems"
        DB["Relational Database"]:::external
        ExtRedis["External Redis"]:::external
        ExtMongo["External MongoDB"]:::external
    end

    %% Data Flow Connections
    Client -->|"HTTP_Request"| Editor
    Editor -->|"Config_and_Test_Request"| Core
    Core -->|"Execute_Scripts"| Script

    %% Core interacts with Plugins
    Core -->|"Plugin_Call"| Cluster
    Core -->|"Plugin_Call"| Component
    Core -->|"Plugin_Call"| Elasticsearch
    Core -->|"Plugin_Call"| Git
    Core -->|"Plugin_Call"| Mongo
    Core -->|"Plugin_Call"| Redis
    Core -->|"Plugin_Call"| SpringDoc
    Core -->|"Plugin_Call"| Swagger
    Core -->|"Plugin_Call"| Task

    %% Core exposes endpoints via Integration Modules
    Core -->|"HTTP_Endpoint"| Jakarta
    Core -->|"HTTP_Endpoint"| JavaEE
    Core -->|"HTTP_Endpoint"| SpringBoot

    %% Plugins and Integration forwarding to External Systems
    Elasticsearch -->|"Query/Update"| DB
    Swagger -->|"Generate_Doc"| DB
    Mongo -->|"Store_Data"| ExtMongo
    Redis -->|"Cache_Data"| ExtRedis

    %% Styles
    classDef external fill:#ffe6e6,stroke:#cc0000,stroke-width:2px;
    classDef core fill:#e6f7ff,stroke:#0056b3,stroke-width:2px;
    classDef plugin fill:#e6ffe6,stroke:#339933,stroke-width:2px;
    classDef integration fill:#fff0b3,stroke:#cc9900,stroke-width:2px;
    classDef editor fill:#e6ccff,stroke:#9933ff,stroke-width:2px;

    %% Click Events
    click Core "https://github.com/ssssssss-team/magic-api/tree/master/magic-api/src/main/java/org/ssssssss/magicapi/core"
    click Script "https://github.com/ssssssss-team/magic-api/tree/master/magic-api/src/main/java/org/ssssssss/magicapi/jsr223"
    click Cluster "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-cluster"
    click Component "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-component"
    click Elasticsearch "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-elasticsearch"
    click Git "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-git"
    click Mongo "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-mongo"
    click Redis "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-redis"
    click SpringDoc "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-springdoc"
    click Swagger "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-swagger"
    click Task "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-plugins/magic-api-plugin-task"
    click Jakarta "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-servlet/magic-api-servlet-jakarta"
    click JavaEE "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-servlet/magic-api-servlet-javaee"
    click SpringBoot "https://github.com/ssssssss-team/magic-api/tree/master/magic-api-spring-boot-starter"
    click Editor "https://github.com/ssssssss-team/magic-api/tree/master/magic-editor/src/main/resources/magic-editor"
```
