# subscan-explorer/subscan-essentials architecture

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

- Interactive diagram: https://gitdiagram.com/subscan-explorer/subscan-essentials
- Repository: https://github.com/subscan-explorer/subscan-essentials

## Overview

##### Main Components
- Backend Service: The Go code under directories like “cmd”, “configs”, “internal”, “model”, “pkg”, “plugins”, “util”, etc. This service handles blockchain data indexing (blocks, extrinsics, events, logs, etc.), processing configuration, and providing HTTP API endpoints.
- API Server: Located under “internal/server/http”, this component handles RESTful APIs that the frontend communicates with.
- Database & Cache: The configuration files in “configs” (and instructions in the README) indicate usage of MySQL (for persistent datastore) and Redis (for caching and possibly pub/sub mechanisms).
- Plugin System: Notice the “plugins” folder with modules for “balance” and “system”. This shows the architecture is extensible via plugins.
- UI / Frontend: The “ui” folder, developed with Nuxt.js, manages the user interface and communicates with the backend API.
- Configuration and Deployment: Files such as “Dockerfile”, “docker-compose.yml”, and config files in “configs” illustrate how the project is deployed and configured.

##### Relationships and Interactions
- The UI communicates with the HTTP API (internal/server/http) over RESTful endpoints.
- The API Server interacts with the business logic found under the “internal/service” directory.
- The data access layer (“internal/dao”, “plugins/*/dao”) handles MySQL and Redis interactions, making use of ORM or direct database calls.
- The plugin system allows custom parsing or extended indexing; plugins integrate with the core service logic and additional HTTP endpoints.
- Order of operation: Client UI → API Gateway → Service Layer → DAO Layer → Database/Cache.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project neatly separates configuration, API handling, business logic, data access, and UI logic.
- Modular Plugin Architecture: This allows additional functionality (such as supporting new protocol features) to be added without modifying the core system.
- Micro-Service/Component-Oriented Design: Although it is a monorepo, the clear separation between “internal” (backend), “plugins”, and “ui” components illustrates loosely coupled parts.
- Clear configuration management using external config files (YAML and TOML) to decouple environment-specific settings.

##### Technologies and Frameworks
- Backend: Written in Go.
- UI: Built using Nuxt.js (Vue.js framework) and AMIS.
- Database: MySQL.
- Caching: Redis.
- Containerization: Docker and docker-compose for quick deployment.
- CI/CD: GitHub Actions (observed in “.github/workflows”) indicate automated testing/building.
- Code Quality: Tools such as golangci-lint are integrated (note the “.golangci.yml”).

## Diagram (Mermaid)

```mermaid
graph TD
  subgraph "Frontend Layer"
    U0["UI / Frontend (Nuxt.js & AMIS)"]:::ui
  end

  subgraph "API and Business Logic"
    A1["Subscan API Server (internal/server/http)"]:::api
    S0["Service Layer (internal/service)"]:::backend
    subgraph "Plugin System"
      P0["Plugin System (plugins)"]:::plugin
      P1["Balance Plugin (plugins/balance)"]:::plugin
      P2["System Plugin (plugins/system)"]:::plugin
    end
  end

  subgraph "Data Layer"
    D1["DAO Layer (internal/dao)"]:::dao
    DB["MySQL Database"]:::db
    RC["Redis Cache"]:::db
  end

  subgraph "Backend Service Codebase"
    B1["cmd"]:::backend
    B2["configs"]:::backend
    B3["internal"]:::backend
    B4["model"]:::backend
    B5["pkg"]:::backend
    B6["util"]:::backend
  end

  subgraph "Configuration & Deployment"
    C1["Dockerfile"]:::config
    C2["docker-compose.yml"]:::config
    C3["docker-compose.db.yml"]:::config
  end

  L["Legend:\n• UI/Frontend: #a2d5f2\n• API Server: #ffcccb\n• Backend Service: #d5f5e3\n• DAO Layer: #f9e79f\n• Databases & Cache: #fad7a0\n• Plugins: #d6eaf8\n• Config & Deployment: #fadbd8"]:::legend

  U0 -->|"REST API Calls"| A1
  A1 -->|"Handles HTTP Requests"| S0
  S0 -->|"Business Logic Processing"| D1
  D1 -->|"Database Operations"| DB
  D1 -->|"Cache Operations"| RC
  S0 -->|"Extends via Plugins"| P0
  P0 --> P1
  P0 --> P2
  B3 -->|"Contains internal logic"| S0
  B2 -->|"Provides configuration"| C1
  C1 -->|"Deployment Builds"| A1

  classDef ui fill:#a2d5f2,stroke:#333,stroke-width:1px;
  classDef api fill:#ffcccb,stroke:#333,stroke-width:1px;
  classDef backend fill:#d5f5e3,stroke:#333,stroke-width:1px;
  classDef dao fill:#f9e79f,stroke:#333,stroke-width:1px;
  classDef db fill:#fad7a0,stroke:#333,stroke-width:1px;
  classDef plugin fill:#d6eaf8,stroke:#333,stroke-width:1px;
  classDef config fill:#fadbd8,stroke:#333,stroke-width:1px;
  classDef legend fill:#ffffff,stroke:#000,stroke-width:1px,font-size:10px,text-align:left;

  click U0 "https://github.com/subscan-explorer/subscan-essentials/tree/master/ui"
  click A1 "https://github.com/subscan-explorer/subscan-essentials/tree/master/internal/server/http"
  click D1 "https://github.com/subscan-explorer/subscan-essentials/tree/master/internal/dao"
  click B1 "https://github.com/subscan-explorer/subscan-essentials/tree/master/cmd"
  click B2 "https://github.com/subscan-explorer/subscan-essentials/tree/master/configs"
  click B3 "https://github.com/subscan-explorer/subscan-essentials/tree/master/internal"
  click B4 "https://github.com/subscan-explorer/subscan-essentials/tree/master/model"
  click B5 "https://github.com/subscan-explorer/subscan-essentials/tree/master/pkg"
  click B6 "https://github.com/subscan-explorer/subscan-essentials/tree/master/util"
  click P0 "https://github.com/subscan-explorer/subscan-essentials/tree/master/plugins"
  click P1 "https://github.com/subscan-explorer/subscan-essentials/tree/master/plugins/balance"
  click P2 "https://github.com/subscan-explorer/subscan-essentials/tree/master/plugins/system"
  click C1 "https://github.com/subscan-explorer/subscan-essentials/tree/master/Dockerfile"
  click C2 "https://github.com/subscan-explorer/subscan-essentials/blob/master/docker-compose.yml"
  click C3 "https://github.com/subscan-explorer/subscan-essentials/blob/master/docker-compose.db.yml"
```
