# rocket-admin/rocketadmin architecture

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

- Interactive diagram: https://gitdiagram.com/rocket-admin/rocketadmin
- Repository: https://github.com/rocket-admin/rocketadmin

## Overview

This project is a full‐stack admin panel solution called “Rocket Admin” that integrates multiple sub‐components. At its core, it is built around a modern, modular Node.js/NestJS backend (with extensive domain modules for business logic such as users, companies, connections, permissions, tables, etc.) and an Angular-based frontend for the admin panel UI. In addition, it contains several supporting services such as a dedicated websocket server (the “autoadmin-ws-server”), a specialized agent (the “rocketadmin-agent”) for executing commands and background tasks, and shared code modules for reusing common data access and helper functionality.

##### Main Components
- Frontend: This is the Angular project (located in the “frontend” folder) which includes user interfaces, routing, UI components, and configuration for environments (with separate configurations for SaaS and non-SaaS modes). It communicates with the backend for data and authentication.
- Backend: The “backend” directory is a comprehensive NestJS-based server that organizes its code in a modular structure (by entities such as user, connection, email, table, etc.). It manages business logic, REST APIs, authorization middleware/guards, and integration with the database.
- Rocketadmin-Agent: Found in the “rocketadmin-agent” directory, this is a specialized microservice/agent. It hosts its own NestJS application to execute commands, integrate with different database systems (as seen by multiple configuration files for DB types), and perform operations like logging and file handling.
- Autoadmin WebSocket Server: The “autoadmin-ws-server” provides websocket connections and controllers for real-time communication.
- Shared Code: The “shared-code” folder includes libraries and data access objects, helper functions, caching logic, and data structures which are used across multiple services (backend and agent). This is key for ensuring consistency in how database connections and operations are handled.
- Infrastructure & Deployment Artifacts: Dockerfiles, docker-compose files, Helm charts, and CI/CD workflows (in .github/workflows) support containerization, orchestration, and deployment.

##### Relationships and Interactions
- The Angular frontend communicates with the backend via RESTful APIs (and possibly websockets for real-time updates).
- The backend serves as the central hub that not only exposes APIs, handles authentication (using JWT with secrets from environment variables) but also organizes extensive use-case modules and data access layers. It interacts with the database (configured via a DATABASE_URL environment variable) and integrates with email and potentially AI services (via the OPENAI_API_KEY).
- The rocketadmin-agent is deployed as a separate container/process and might perform operations asynchronously (triggered by scheduled jobs or user actions) and interact with both the backend and directly with various database systems, as its file tree includes command executors and helpers for encryption, logging, and configuration.
- The autoadmin-ws-server provides a websocket interface which may be used for delivering real-time system notifications or admin command feedback.
- The shared-code library is used by multiple components (agent, backend, etc.) to ensure consistency in data access and business rules.

##### Important Architectural Patterns and Design Principles
- Modular / Layered Architecture: The backend is split into numerous domains (e.g., user, connection, email, table, etc.) where controllers, services (use-cases), repositories, and utilities are well separated.
- Microservices/Service Separation: Deployment artifacts (Dockerfiles, docker-compose, and Helm charts) and separate codebases for the frontend, backend, agent, and websocket server indicate a distributed, containerized design.
- Use of Dependency Injection and Repositories: Evident in the backend (NestJS) structure where many directories under “entities” include repository interfaces and extensions.
- Cross-cutting Concerns Handling: The project includes middleware, guards, interceptors, logging, and exception handling mechanisms to enforce security, data validation, and error management consistently across services.
- Shared Library Pattern: The “shared-code” directory encapsulates common functionality that is injected where necessary.

##### Relevant Technologies and Frameworks
- Frontend: Angular (with Angular CLI, Karma, Protractor, Sass, and Nginx for static file serving).
- Backend: NestJS (TypeScript, dependency injection, and middleware), REST APIs, and integration with various databases.
- Infrastructure: Docker (with multiple Dockerfiles and docker-compose setups), Helm for Kubernetes deployments, CI/CD pipelines via GitHub Actions.
- Agent: Likely built using NestJS as well with specialized command execution logic.
- Database Access & ORM: Custom repository implementations and migration scripts indicate robust database management.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend"
        FE["Angular Frontend"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Services"
        BE["NestJS Backend API"]:::backend
        DB["Database"]:::database
    end

    %% Common Code
    subgraph "Common Modules"
        SC["Shared Code Library"]:::shared
    end

    %% Microservices
    subgraph "Microservices"
        RA["Rocketadmin-Agent"]:::agent
        WS["Autoadmin WebSocket Server"]:::ws
    end

    %% Infrastructure & Deployment Artifacts
    subgraph "Infrastructure & Deployment Artifacts"
        INF["Deployment"]:::infraGroup
        D1[".github/workflows"]:::infra
        D2["Dockerfile"]:::infra
        D3["docker-compose.yml"]:::infra
        D4["docker-bake*.hcl"]:::infra
        D5["docs"]:::infra
    end

    %% Connections between layers
    FE -->|"RESTAPI"| BE
    BE -->|"queries"| DB
    BE -->|"uses"| SC
    RA -->|"communicates"| BE
    RA -->|"uses"| SC
    WS -->|"realtime"| BE
    FE <-->|"notifications"| WS

    %% Infrastructure connections (services are deployed using containerization)
    FE -->|"deployedVia"| INF
    BE -->|"deployedVia"| INF
    RA -->|"deployedVia"| INF
    WS -->|"deployedVia"| INF

    %% Deployment artifacts backing the deployment node
    INF --> D1
    INF --> D2
    INF --> D3
    INF --> D4
    INF --> D5

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef agent fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef ws fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef shared fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef database fill:#ffeeba,stroke:#856404,stroke-width:2px;
    classDef infra fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef infraGroup fill:#bee5eb,stroke:#0c5460,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/rocket-admin/rocketadmin/tree/main/frontend"
    click BE "https://github.com/rocket-admin/rocketadmin/tree/main/backend"
    click RA "https://github.com/rocket-admin/rocketadmin/tree/main/rocketadmin-agent"
    click WS "https://github.com/rocket-admin/rocketadmin/tree/main/autoadmin-ws-server"
    click SC "https://github.com/rocket-admin/rocketadmin/tree/main/shared-code"
    click D1 "https://github.com/rocket-admin/rocketadmin/tree/main/.github/workflows"
    click D2 "https://github.com/rocket-admin/rocketadmin/tree/main/Dockerfile"
    click D3 "https://github.com/rocket-admin/rocketadmin/blob/main/docker-compose.yml"
    click D4 "https://github.com/rocket-admin/rocketadmin/blob/main/docker-bake*.hcl"
    click D5 "https://github.com/rocket-admin/rocketadmin/tree/main/docs"
```
