# untangledfinance/untangled-web architecture

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

- Interactive diagram: https://gitdiagram.com/untangledfinance/untangled-web
- Repository: https://github.com/untangledfinance/untangled-web

## Overview

##### Project type and purpose
- Untangled Web is an open-source Node.js library (SDK/framework) for building web applications on the Untangled platform.
- It provides a bootstrapping system (decorators + loaders), a pluggable core (HTTP servers, caching, scheduling, storage, etc.), connectors for external services (Redis, MongoDB, GCS), and middleware abstractions.

##### File structure
- Top‐level directories:
- src/boot – decorators & loaders that initialize beans, configs, connectors
- src/core – fundamental subsystems (http, caching, ioc, logging, jwt, scheduling, storage, validation…)
- src/connectors – implementations for specific external services (redis, mongo, google-cloud storage…)
- src/middlewares – reusable middleware (auth, rate-limit)
- examples/ – sample applications (cron job, simple web app) demonstrating usage
- Config/build files: package.json, tsconfig.json, .devcontainer, scripts for publishing.

##### Detail
- Every sub-layer you plan to support (e.g., show both Redis and Mongo under Connectors)
- Decorator/loader sequence explicitly if it’s central to getting started
- Don’t just show “Core”—break it into HTTP server, IOC container, scheduling, etc., to reflect the code layout

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Applications
    subgraph "Developer Application" 
        AppWeb["Simple Web App"]:::app
        AppCron["Simple Cron App"]:::app
    end

    %% Boot Layer
    subgraph "Boot Layer"
        BI["index.ts"]:::boot
        subgraph "Decorators"
            BDec1["cache.ts"]:::boot
            BDec2["proxy.ts"]:::boot
            BDec3["index.ts"]:::boot
        end
        subgraph "Loaders"
            BLoad1["config.ts"]:::boot
            BLoad2["bean.ts"]:::boot
            BLoad3["index.ts"]:::boot
            BLoad4["types.ts"]:::boot
        end
    end

    %% Core Layer
    subgraph "Core Layer"
        subgraph "HTTP Server"
            HTTPIndexServer["index.ts"]:::core
            ExpressAdapter["express.ts"]:::core
            FastifyAdapter["fastify.ts"]:::core
        end
        subgraph "HTTP Core & Context"
            HTTPCore["core.ts"]:::core
            HTTPContext["context.ts"]:::core
            HTTPError["error.ts"]:::core
            HTTPProxy["proxy.ts"]:::core
            HTTPIndexCore["index.ts"]:::core
        end
        IOC["IOC Container"]:::core
        ConfigCore["Configuration"]:::core
        CachingCore["Caching Core"]:::core
        CachingCoreIndex["caching/index.ts"]:::core
        Scheduling["Scheduling"]:::core
        Logging["Logging"]:::core
        JWT["JWT Auth"]:::core
        Validation["Validation"]:::core
        ContextProp["Context Propagation"]:::core
        Encoding["Encoding Utilities"]:::core
        Notification["Notification"]:::core
        RBAC["RBAC"]:::core
        StorageCore["Storage Abstraction"]:::core
        subgraph "Tunneling"
            TunnelIndex["index.ts"]:::core
            SSH["ssh.ts"]:::core
        end
        Types["Type Definitions"]:::core
    end

    %% Connectors Layer
    subgraph "Connectors Layer"
        subgraph "Caching"
            RedisCon["redis.ts"]:::connectors
            CachingIndexCon["index.ts"]:::connectors
        end
        subgraph "MongoDB"
            MongoClient["client.ts"]:::connectors
            MongoHTTP["http.ts"]:::connectors
            MongoTypes["types.ts"]:::connectors
            MongoIndex["index.ts"]:::connectors
        end
        subgraph "Storage"
            GCS["google-cloud.ts"]:::connectors
            StorageIndexCon["index.ts"]:::connectors
        end
    end

    %% Middleware Layer
    subgraph "Middleware Layer"
        AuthMW["auth"]:::middleware
        RateLimitMW["rate-limit"]:::middleware
    end

    %% External Services
    subgraph "External Services"
        Redis["Redis Cluster"]:::external
        Mongo["MongoDB"]:::external
        GCSService["Google Cloud Storage"]:::external
        APIs["HTTP Clients / External APIs"]:::external
    end

    %% Connections
    AppWeb --> BI
    AppCron --> BI

    BI -->|"loads decorators"|BDec1
    BI -->BDec2
    BI -->BDec3
    BI -->|"loads loaders"|BLoad1
    BI -->BLoad2
    BI -->BLoad3
    BI -->BLoad4
    BI --> HTTPIndexServer

    HTTPIndexServer --> ExpressAdapter
    HTTPIndexServer --> FastifyAdapter
    ExpressAdapter --> HTTPCore
    FastifyAdapter --> HTTPCore
    HTTPCore --> HTTPContext
    HTTPCore --> HTTPError
    HTTPCore --> HTTPProxy
    HTTPCore --> HTTPIndexCore

    HTTPIndexCore --> AuthMW
    AuthMW --> RateLimitMW
    RateLimitMW --> IOC

    IOC --> ConfigCore
    IOC --> CachingCore
    IOC --> Scheduling
    IOC --> Logging
    IOC --> JWT
    IOC --> Validation
    IOC --> ContextProp
    IOC --> Encoding
    IOC --> Notification
    IOC --> RBAC
    IOC --> StorageCore
    IOC --> TunnelIndex
    IOC --> Types

    CachingCore --> RedisCon
    CachingCoreIndex --> RedisCon
    RedisCon --> Redis

    StorageCore --> GCS
    StorageIndexCon --> GCS
    GCS --> GCSService

    StorageCore --> MongoClient
    MongoIndex --> MongoClient
    MongoClient --> Mongo

    APIs -->|calls| HTTPCore

    %% Click Events
    click AppWeb "https://github.com/untangledfinance/untangled-web/tree/main/examples/simple-web-app"
    click AppCron "https://github.com/untangledfinance/untangled-web/tree/main/examples/simple-cron-app"
    click BI "https://github.com/untangledfinance/untangled-web/blob/main/src/boot/index.ts"
    click BDec1 "https://github.com/untangledfinance/untangled-web/blob/main/src/boot/decorators/cache.ts"
    click BDec2 "https://github.com/untangledfinance/untangled-web/blob/main/src/boot/decorators/proxy.ts"
    click BDec3 "https://github.com/untangledfinance/untangled-web/blob/main/src/boot/decorators/index.ts"
    click BLoad1 "https://github.com/untangledfinance/untangled-web/blob/main/src/boot/loaders/config.ts"
    click BLoad2 "https://github.com/untangledfinance/untangled-web/blob/main/src/boot/loaders/bean.ts"
    click BLoad3 "https://github.com/untangledfinance/untangled-web/blob/main/src/boot/loaders/index.ts"
    click BLoad4 "https://github.com/untangledfinance/untangled-web/blob/main/src/boot/loaders/types.ts"
    click HTTPIndexServer "https://github.com/untangledfinance/untangled-web/blob/main/src/core/http/server/index.ts"
    click ExpressAdapter "https://github.com/untangledfinance/untangled-web/blob/main/src/core/http/server/express.ts"
    click FastifyAdapter "https://github.com/untangledfinance/untangled-web/blob/main/src/core/http/server/fastify.ts"
    click HTTPCore "https://github.com/untangledfinance/untangled-web/blob/main/src/core/http/core.ts"
    click HTTPContext "https://github.com/untangledfinance/untangled-web/blob/main/src/core/http/context.ts"
    click HTTPError "https://github.com/untangledfinance/untangled-web/blob/main/src/core/http/error.ts"
    click HTTPProxy "https://github.com/untangledfinance/untangled-web/blob/main/src/core/http/proxy.ts"
    click HTTPIndexCore "https://github.com/untangledfinance/untangled-web/blob/main/src/core/http/index.ts"
    click IOC "https://github.com/untangledfinance/untangled-web/blob/main/src/core/ioc/index.ts"
    click ConfigCore "https://github.com/untangledfinance/untangled-web/blob/main/src/core/config/index.ts"
    click CachingCore "https://github.com/untangledfinance/untangled-web/blob/main/src/core/caching/core.ts"
    click CachingCoreIndex "https://github.com/untangledfinance/untangled-web/blob/main/src/core/caching/index.ts"
    click Scheduling "https://github.com/untangledfinance/untangled-web/blob/main/src/core/scheduling/index.ts"
    click Logging "https://github.com/untangledfinance/untangled-web/blob/main/src/core/logging/index.ts"
    click JWT "https://github.com/untangledfinance/untangled-web/blob/main/src/core/jwt/index.ts"
    click Validation "https://github.com/untangledfinance/untangled-web/blob/main/src/core/validation/index.ts"
    click ContextProp "https://github.com/untangledfinance/untangled-web/blob/main/src/core/context/index.ts"
    click Encoding "https://github.com/untangledfinance/untangled-web/blob/main/src/core/encoding/index.ts"
    click Notification "https://github.com/untangledfinance/untangled-web/blob/main/src/core/notify/index.ts"
    click RBAC "https://github.com/untangledfinance/untangled-web/blob/main/src/core/rbac/index.ts"
    click StorageCore "https://github.com/untangledfinance/untangled-web/blob/main/src/core/storage/index.ts"
    click TunnelIndex "https://github.com/untangledfinance/untangled-web/blob/main/src/core/tunneling/index.ts"
    click SSH "https://github.com/untangledfinance/untangled-web/blob/main/src/core/tunneling/ssh.ts"
    click Types "https://github.com/untangledfinance/untangled-web/blob/main/src/core/types/index.ts"
    click RedisCon "https://github.com/untangledfinance/untangled-web/blob/main/src/connectors/caching/redis.ts"
    click CachingIndexCon "https://github.com/untangledfinance/untangled-web/blob/main/src/connectors/caching/index.ts"
    click MongoClient "https://github.com/untangledfinance/untangled-web/blob/main/src/connectors/mongo/client.ts"
    click MongoHTTP "https://github.com/untangledfinance/untangled-web/blob/main/src/connectors/mongo/http.ts"
    click MongoTypes "https://github.com/untangledfinance/untangled-web/blob/main/src/connectors/mongo/types.ts"
    click MongoIndex "https://github.com/untangledfinance/untangled-web/blob/main/src/connectors/mongo/index.ts"
    click GCS "https://github.com/untangledfinance/untangled-web/blob/main/src/connectors/storage/google-cloud.ts"
    click StorageIndexCon "https://github.com/untangledfinance/untangled-web/blob/main/src/connectors/storage/index.ts"
    click AuthMW "https://github.com/untangledfinance/untangled-web/blob/main/src/middlewares/auth/index.ts"
    click RateLimitMW "https://github.com/untangledfinance/untangled-web/blob/main/src/middlewares/rate-limit/index.ts"

    %% Styles
    classDef app fill:#f9f,stroke:#333,stroke-width:1px
    classDef boot fill:#bbdefb,stroke:#0d47a1,stroke-width:1px
    classDef core fill:#c8e6c9,stroke:#1b5e20,stroke-width:1px
    classDef connectors fill:#ffe0b2,stroke:#e65100,stroke-width:1px
    classDef middleware fill:#d1c4e9,stroke:#4a148c,stroke-width:1px
    classDef external fill:#eeeeee,stroke:#616161,stroke-width:1px
```
