# dumbwareio/dumbassets architecture

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

- Interactive diagram: https://gitdiagram.com/dumbwareio/dumbassets
- Repository: https://github.com/dumbwareio/dumbassets

## Overview

##### Project type and purpose
- DumbAssets is a self-contained, full-stack web application:
- Backend: Node.js + Express monolith
- Frontend: Vanilla JavaScript SPA served as static assets
- Data store: JSON files + local filesystem for images/receipts
- Additional behavior: scheduled maintenance & warranty notifications via Apprise

##### Main components
- Client (Browser/PWA)
– public/index.html + login.html + script.js + service-worker.js
– UI managers (charts, dashboardManager, modalManager, etc.)
– Helper modules (paths, utils, serviceWorkerHelper)
- Server (Node.js/Express)
– Entry point: server.js
– Middleware layer:
· cors.js (CORS)
· demo.js (read-only/demo mode)
· express-rate-limit, helmet, compression, cookie-parser, express-session
– Routing & Controllers: static hosting (public/), API endpoints (assets, auth, file uploads, notifications)
– Service layer (src/services):
· fileUpload: Multer-based upload handling, image/receipt storage, UUID naming
· notifications: Apprise HTTP integration, notificationQueue, warrantyCron (node-cron scheduler)
· render: assetRenderer, listRenderer, previewRenderer (generate HTML snippets or JSON payloads)
- Data Storage
– `/data/*.json`: Assets.json, SubAssets.json, config.json
– `/data/Images`, `/data/Receipts` on disk
- External Services
– Apprise server (via APPRISE_URL) for sending Discord/Telegram/ntfy notifications
- DevOps & Deployment
– Dockerfile + docker-compose.yml for containerization
– .env + .env.example for config
– scripts for PWA manifest and maintenance tests

##### Relationships & interactions
1. Browser ←→ HTTP(S) → Express server:
- Static assets (HTML/JS/CSS)
- API calls for CRUD on assets, components, tags
- File upload endpoints → fileUpload service → writes to `/data/Images` or `/data/Receipts`
2. Server
- Middleware chain processes requests (CORS, sessions, rate-limit, demo mode)
- Routes dispatch to service layer
- Service layer reads/writes JSON files via fs-extra
- Render services build dynamic fragments or data views
3. Scheduler
- node-cron (warrantyCron) triggers at configured intervals
- notificationQueue enqueues notifications → appriseNotifier sends via HTTP
4. Container
- Docker encapsulates server + data volume mount

##### Architectural patterns & design principles
- Layered architecture: Presentation (static SPA), API, Services, Data
- Modular service separation (fileUpload, notifications, render)
- Middleware pipeline for cross-cutting concerns
- Single-process monolith inside Docker
- Use of JSON files as “lightweight DB”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    EndUser("End User (Browser/PWA)"):::external
    ExternalApprise("Apprise Service"):::external

    subgraph "DumbAssets Docker Container"
        direction TB

        %% Frontend Layer
        subgraph "Client (Browser/PWA)" 
            direction TB
            Index["index.html"]:::client
            Login["login.html"]:::client
            Script["script.js"]:::client
            SW["service-worker.js"]:::client
            ConfigJS["config.js"]:::client
            Styles["styles.css"]:::client
            Helpers["helpers/"]:::client
            Managers["managers/"]:::client
            AssetsStatic["assets/"]:::client
            JSEnh["js/"]:::client
        end

        %% Express Server Layer
        subgraph "Express Server" 
            direction TB
            ServerJs["server.js"]:::server

            subgraph "Middleware Stack"
                direction TB
                CORS["cors.js"]:::server
                Demo["demo.js"]:::server
                RateLimit["express-rate-limit"]:::server
                Security["helmet/compression"]:::server
                Session["cookie-parser/session"]:::server
            end

            subgraph "API & Controllers"
                direction TB
                APIEndpoints["Routes & Controllers"]:::server
            end

            subgraph "Services Layer"
                direction TB
                subgraph "File Upload Service"
                    FileIndex["index.js"]:::server
                    FileUp["fileUploader.js"]:::server
                    FileInit["init.js"]:::server
                    FileUtils["utils.js"]:::server
                end
                subgraph "Notifications Service"
                    AppriseNotifier["appriseNotifier.js"]:::server
                    NotifyQueue["notificationQueue.js"]:::server
                    WarrantyCron["warrantyCron.js"]:::server
                    NotifyUtils["utils.js"]:::server
                end
                subgraph "Render Service"
                    RenderIndex["index.js"]:::server
                    AssetRenderer["assetRenderer.js"]:::server
                    ListRenderer["listRenderer.js"]:::server
                    PreviewRenderer["previewRenderer.js"]:::server
                    SyncHelper["syncHelper.js"]:::server
                end
            end
        end

        %% Scheduler
        WarrantyCronNode["node-cron Scheduler"]:::server

        %% Data Storage
        subgraph "Data Storage (Filesystem & JSON)" 
            direction TB
            AssetsJSON["Assets.json"]:::storage
            SubAssetsJSON["SubAssets.json"]:::storage
            ConfigJSON["config.json"]:::storage
            ImagesDir["Images/"]:::storage
            ReceiptsDir["Receipts/"]:::storage
        end
    end

    %% Connections
    EndUser -->|"HTTP GET"| Index
    EndUser -->|"HTTP GET"| Login
    EndUser -->|"Service Worker"| SW
    Index -->|"Fetch AJAX"| APIEndpoints
    Script -->|"Calls API"| APIEndpoints
    APIEndpoints -->|"invoke"| CORS
    CORS --> Demo
    Demo --> RateLimit
    RateLimit --> Security
    Security --> Session
    Session --> APIEndpoints
    APIEndpoints -->|"calls"| FileIndex
    FileIndex --> FileUp
    FileIndex --> FileInit
    FileUp -->|"writes"| ImagesDir
    FileUp -->|"writes"| ReceiptsDir
    APIEndpoints -->|"calls"| AppriseNotifier
    WarrantyCronNode --> NotifyQueue
    NotifyQueue --> AppriseNotifier
    AppriseNotifier -->|"HTTP POST"| ExternalApprise
    WarrantyCronNode -->|"cron"| WarrantyCronNode
    APIEndpoints -->|"calls"| RenderIndex
    RenderIndex --> AssetRenderer
    RenderIndex --> ListRenderer
    RenderIndex --> PreviewRenderer
    RenderIndex --> SyncHelper
    FileIndex -->|"fs R/W"| AssetsJSON
    FileIndex -->|"fs R/W"| SubAssetsJSON
    FileIndex -->|"fs R/W"| ConfigJSON

    %% Click Events - Frontend
    click Index "https://github.com/dumbwareio/dumbassets/blob/main/public/index.html"
    click Login "https://github.com/dumbwareio/dumbassets/blob/main/public/login.html"
    click Script "https://github.com/dumbwareio/dumbassets/blob/main/public/script.js"
    click SW "https://github.com/dumbwareio/dumbassets/blob/main/public/service-worker.js"
    click Helpers "https://github.com/dumbwareio/dumbassets/tree/main/public/helpers/"
    click Managers "https://github.com/dumbwareio/dumbassets/tree/main/public/managers/"
    click AssetsStatic "https://github.com/dumbwareio/dumbassets/tree/main/public/assets/"
    click JSEnh "https://github.com/dumbwareio/dumbassets/tree/main/public/js/"
    click ConfigJS "https://github.com/dumbwareio/dumbassets/blob/main/public/config.js"
    click Styles "https://github.com/dumbwareio/dumbassets/blob/main/public/styles.css"

    %% Click Events - Server
    click ServerJs "https://github.com/dumbwareio/dumbassets/blob/main/server.js"
    click CORS "https://github.com/dumbwareio/dumbassets/blob/main/middleware/cors.js"
    click Demo "https://github.com/dumbwareio/dumbassets/blob/main/middleware/demo.js"

    %% Click Events - Services Layer
    click FileIndex "https://github.com/dumbwareio/dumbassets/blob/main/src/services/fileUpload/index.js"
    click FileUp "https://github.com/dumbwareio/dumbassets/blob/main/src/services/fileUpload/fileUploader.js"
    click FileInit "https://github.com/dumbwareio/dumbassets/blob/main/src/services/fileUpload/init.js"
    click FileUtils "https://github.com/dumbwareio/dumbassets/blob/main/src/services/fileUpload/utils.js"
    click AppriseNotifier "https://github.com/dumbwareio/dumbassets/blob/main/src/services/notifications/appriseNotifier.js"
    click NotifyQueue "https://github.com/dumbwareio/dumbassets/blob/main/src/services/notifications/notificationQueue.js"
    click WarrantyCron "https://github.com/dumbwareio/dumbassets/blob/main/src/services/notifications/warrantyCron.js"
    click NotifyUtils "https://github.com/dumbwareio/dumbassets/blob/main/src/services/notifications/utils.js"
    click RenderIndex "https://github.com/dumbwareio/dumbassets/blob/main/src/services/render/index.js"
    click AssetRenderer "https://github.com/dumbwareio/dumbassets/blob/main/src/services/render/assetRenderer.js"
    click ListRenderer "https://github.com/dumbwareio/dumbassets/blob/main/src/services/render/listRenderer.js"
    click PreviewRenderer "https://github.com/dumbwareio/dumbassets/blob/main/src/services/render/previewRenderer.js"
    click SyncHelper "https://github.com/dumbwareio/dumbassets/blob/main/src/services/render/syncHelper.js"

    %% Styles
    classDef client fill:#CAE8FF,stroke:#3B7DDD,color:#000
    classDef server fill:#C8E6C9,stroke:#357A38,color:#000
    classDef storage fill:#E0E0E0,stroke:#616161,color:#000
    classDef external fill:#FFE0B2,stroke:#FF8F00,color:#000
```
