# dasmeta/nodebb-plugin-upload architecture

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

- Interactive diagram: https://gitdiagram.com/dasmeta/nodebb-plugin-upload
- Repository: https://github.com/dasmeta/nodebb-plugin-upload

## Overview

##### Project type and purpose
- This is a NodeBB plugin (“NodeBB Upload plugin”) whose purpose is to add file‑upload capability to a NodeBB forum, storing assets on S3, Google Cloud Storage, or Minio.
- It hooks into NodeBB’s plugin system and admin UI, reads configuration from environment variables or the NodeBB database, and streams uploaded files to an external object‑storage service.

##### File structure
- Top‑level files
- package.json, index.js – entry point and plugin entry definitions
- plugin.json – metadata about the plugin (hooks, scripts)
- README.md – user documentation
- .eslintrc.js, .gitignore – linting and VCS
- templates/admin/plugins/upload.tpl – UI template injected into NodeBB’s Admin panel
- No dedicated “src” or “lib” folder: logic lives in index.js.

##### README for additional insights
- Shows three supported providers (S3, GCS, Minio)
- Configuration via environment variables or NodeBB Admin (persisted in the DB)
- Notes on credential precedence: DB‑stored settings override ENV vars.

a. NodeBB Forum Platform
– Core NodeBB server process (Express/Socket.io)
– NodeBB Database (MongoDB or Redis)
b. Upload Plugin
– Initialization / hook registration
– Config Loader (reads ENV vars and/or DB settings)
– Admin UI component (template)
– Upload Handler (receives multipart uploads, generates file key/URL)
c. External Object Storage Services
– AWS S3
– Google Cloud Storage
– Minio
d. DevOps / Configuration
– Environment Variables
– NodeBB Admin panel storing settings in the DB

##### Relationships and interactions
1. Administrator configures upload settings via NodeBB Admin UI
→ Plugin writes config to NodeBB Database
2. At plugin initialization, Config Loader reads ENV vars and/or DB
→ Populates runtime settings object
3. End user submits file via NodeBB forum UI
→ Upload Handler (plugin code in NodeBB)
→ Streams file data to chosen provider SDK/API
→ Receives a public URL or key
→ Returns URL to NodeBB, which stores reference in posts
4. Client browser loads images/CSS/JS from the object‑storage asset host

##### Architectural patterns and design principles
- Plugin-based extensibility: adheres to NodeBB’s hook system
- Configuration fallback: environment variables first, then DB
- Streaming large payloads directly from NodeBB to provider (no local file persist)
- Single Responsibility: separate template/UI, config, upload logic

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% NodeBB Core
    subgraph "NodeBB Core"
        direction TB
        Core["Express / Socket.io"]:::blue
        Manager["Plugin Manager"]:::blue
    end

    %% Upload Plugin
    subgraph "Upload Plugin"
        direction TB
        Init["Initialization / Hook Registration"]:::green
        Config["Config Loader (ENV & DB)"]:::green
        AdminUI["Admin UI Component"]:::green
        UploadHandler["Upload Handler"]:::green
        Metadata["Plugin Metadata"]:::green
        PackageDef["Package Definition & Dependencies"]:::green
        Docs["Documentation & User Guide"]:::green
        Lint["Linting Configuration"]:::green
        CICD["CI/CD Pipeline"]:::green
    end

    %% Database and Environment
    DB["NodeBB Database"]:::gray
    ENV["Environment Variables"]:::external

    %% External Storage
    subgraph "External Storage Providers"
        direction TB
        S3["AWS S3"]:::orange
        GCS["Google Cloud Storage"]:::orange
        Minio["Minio"]:::orange
    end

    %% End User
    User["End User (Browser)"]:::external

    %% Runtime Flow
    User -->|"Submits file"| Core
    Core -->|"Invokes upload"| UploadHandler
    UploadHandler -->|"Streams file via SDK/API"| S3
    UploadHandler -->|"Streams file via SDK/API"| GCS
    UploadHandler -->|"Streams file via SDK/API"| Minio
    S3 -->|"Returns URL/key"| UploadHandler
    GCS -->|"Returns URL/key"| UploadHandler
    Minio -->|"Returns URL/key"| UploadHandler
    UploadHandler -->|"Saves reference in post"| Core
    Core -->|"Delivers response with URL"| User

    %% Configuration Flow
    AdminUI -->|"Writes settings"| DB
    DB -->|"Reads config"| Config
    ENV -->|"Provides fallback config"| Config
    Config -->|"Supplies runtime settings"| Init
    Init -->|"Registers hooks"| Manager

    %% Click Events
    click Init "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/index.js"
    click Config "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/index.js"
    click UploadHandler "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/index.js"
    click AdminUI "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/templates/admin/plugins/upload.tpl"
    click Metadata "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/plugin.json"
    click PackageDef "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/package.json"
    click Docs "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/README.md"
    click Lint "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/.eslintrc.js"
    click CICD "https://github.com/dasmeta/nodebb-plugin-upload/blob/master/.github/workflows/npm-publish.yaml"

    %% Styles
    classDef blue fill:#E8F4FD,stroke:#2196F3;
    classDef green fill:#E8F8E2,stroke:#4CAF50;
    classDef orange fill:#FFF4E5,stroke:#FF9800;
    classDef gray fill:#F0F0F0,stroke:#BDBDBD;
    classDef external fill:#FFFFFF,stroke:#999999,stroke-dasharray: 5 5;
```
