# deskree-inc/nanoservice-ts architecture

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

- Interactive diagram: https://gitdiagram.com/deskree-inc/nanoservice-ts
- Repository: https://github.com/deskree-inc/nanoservice-ts

## Overview

##### Project Type and Purpose
- This is an open-source framework (nanoservice-ts) primarily targeting backend development with a focus on lightweight, modular, and scalable “nanoservices.”
- Its key purpose is to let developers build backend applications as discrete, single-responsibility units (nodes) that get composed into workflows. The framework also includes CLI tooling, templates, a runtime engine, and integrations with triggers (HTTP and gRPC).

##### File Structure to Identify Major Components
- Core Engine & Runners:
- The “core” directory contains runner components (core/runner) that manage configuration, node execution, logging, storage, and the orchestration logic.
- The “core/shared” library contains common utilities and type definitions that are shared across the system.
- “core/workflow-helper” appears to include helper components for workflow composition and management.
- Nodes and Triggers:
- The “nodes” directory is organized into subdirectories (e.g., control-flow and web) and contains different types of nodes (e.g., “if-else”, “api-call”, “react”) that implement business logic.
- The “triggers” directory has sub-folders such as “grpc” and “http” which implement trigger mechanisms that start workflows.
- CLI and Templates:
- The “packages/cli” folder contains the command line interface source code (commands for project creation, development, and workflow creation).
- The “templates” directory provides ready-made UI and node templates to help kickstart new projects.
- Runtimes & SDK:
- The “runtimes” directory (especially the “python3” sub-folder) lists runtime implementations that allow different languages to run nanoservices.
- The “sdk” folder (for example, sdk/javascript) gives client-side or integration libraries for using nanoservice features.
- Infrastructure and Documentation:
- The “infra” folder holds deployment configuration files (docker-compose, Prometheus, Grafana, Loki, etc.) to monitor and deploy the services.
- The “docs” folder documents the system with architecture overviews, developer guides, and reference material.

##### Relationships and Interactions
- The Runner (core/runner) is the central orchestrator that loads configurations, executes nodes, and processes triggers.
- Nodes (in nodes/, runtimes/, templates) encapsulate business functionality and are plugged into workflows.
- Triggers (in triggers/) serve as the entry points that listen for events (via HTTP or gRPC) and then activate the corresponding workflows.
- CLI (packages/cli) is used to scaffold new projects, create nodes, and manage workflows.
- Shared services (core/shared) provide common functionality (logging, error handling, metrics) used by both the runner and nodes.
- The infrastructure components (infra/) support deployment, observability, and monitoring of the live system.

##### Important Architectural Patterns and Technologies
- The framework is built on a modular, nanoservices architecture with emphasis on the Single Responsibility Principle – meaning each component (node, trigger, runner) has clear, isolated functionality.
- Communication flows from external trigger entry points to the runner, which then orchestrates the execution of workflow nodes either synchronously or asynchronously.
- Node modules appear to communicate via defined schemas and types (referenced in many .ts files and proto definitions), suggesting that gRPC and HTTP protocols are instrumental.
- The CLI simplifies developing and managing these components in a consistent TypeScript environment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine & Runners
    subgraph "Core Engine & Runners"
        ORD["Runner/Orchestrator"]:::orchestrator
        SHARED["Shared Utilities/Services"]:::orchestrator
        WF_HELPER["Workflow Helper"]:::orchestrator
    end

    %% Nodes
    subgraph "Nodes"
        CONTROL["Control Flow Nodes"]:::node
        WEB["Web Nodes"]:::node
    end

    %% Triggers
    subgraph "Triggers"
        GRPC["gRPC Trigger"]:::trigger
        HTTP["HTTP Trigger"]:::trigger
    end

    %% CLI & Templates
    subgraph "CLI & Templates"
        CLI["CLI/Project Management"]:::cli
        TEMPL_UI["Templates (UI)"]:::template
        TEMPL_NODE["Templates (Node)"]:::template
    end

    %% Runtimes & SDK
    subgraph "Runtimes & SDK"
        RUNTIME["Runtimes (Python3)"]:::runtime
        SDK["SDK (JavaScript)"]:::sdk
    end

    %% Supporting Infrastructure
    subgraph "Supporting Infrastructure"
        INFRA["Infrastructure (Deployment & Monitoring)"]:::infra
        DOCS["Documentation"]:::docs
    end

    %% Connections
    GRPC -->|"triggers"| ORD
    HTTP -->|"triggers"| ORD

    CLI -->|"configures"| ORD
    CLI -->|"initiates"| CONTROL
    CLI -->|"initiates"| WEB

    ORD <-->|"logs-metrics"| SHARED
    ORD -->|"orchestrates"| WF_HELPER

    ORD -->|"executes"| CONTROL
    ORD -->|"executes"| WEB

    WF_HELPER -->|"assists"| CONTROL
    WF_HELPER -->|"assists"| WEB

    TEMPL_UI -->|"providesTemplates"| CONTROL
    TEMPL_NODE -->|"providesTemplates"| WEB

    RUNTIME -->|"runs"| CONTROL
    RUNTIME -->|"runs"| WEB

    SDK -->|"integratesWith"| ORD

    INFRA -->|"monitors"| ORD
    INFRA -->|"monitors"| WF_HELPER

    DOCS -.->|"references"| ORD
    DOCS -.->|"references"| WF_HELPER
    DOCS -.->|"references"| CLI

    %% Click Events
    click ORD "https://github.com/deskree-inc/nanoservice-ts/tree/main/core/runner"
    click SHARED "https://github.com/deskree-inc/nanoservice-ts/tree/main/core/shared"
    click WF_HELPER "https://github.com/deskree-inc/nanoservice-ts/tree/main/core/workflow-helper"
    click CONTROL "https://github.com/deskree-inc/nanoservice-ts/tree/main/nodes/control-flow"
    click WEB "https://github.com/deskree-inc/nanoservice-ts/tree/main/nodes/web"
    click GRPC "https://github.com/deskree-inc/nanoservice-ts/tree/main/triggers/grpc"
    click HTTP "https://github.com/deskree-inc/nanoservice-ts/tree/main/triggers/http"
    click CLI "https://github.com/deskree-inc/nanoservice-ts/tree/main/packages/cli"
    click TEMPL_UI "https://github.com/deskree-inc/nanoservice-ts/tree/main/templates/node-ui"
    click TEMPL_NODE "https://github.com/deskree-inc/nanoservice-ts/tree/main/templates/node"
    click RUNTIME "https://github.com/deskree-inc/nanoservice-ts/tree/main/runtimes/python3"
    click SDK "https://github.com/deskree-inc/nanoservice-ts/tree/main/sdk/javascript"
    click INFRA "https://github.com/deskree-inc/nanoservice-ts/tree/main/infra"
    click DOCS "https://github.com/deskree-inc/nanoservice-ts/tree/main/docs"

    %% Styles
    classDef orchestrator fill:#AEDFF7,stroke:#333,stroke-width:2px;
    classDef node fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef trigger fill:#FFECB3,stroke:#333,stroke-width:2px;
    classDef cli fill:#FFCDD2,stroke:#333,stroke-width:2px;
    classDef template fill:#B2EBF2,stroke:#333,stroke-width:2px;
    classDef runtime fill:#E1BEE7,stroke:#333,stroke-width:2px;
    classDef sdk fill:#DCEDC8,stroke:#333,stroke-width:2px;
    classDef infra fill:#D1C4E9,stroke:#333,stroke-width:2px;
    classDef docs fill:#F0F4C3,stroke:#333,stroke-width:2px;
```
