# instana/nodejs architecture

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

- Interactive diagram: https://gitdiagram.com/instana/nodejs
- Repository: https://github.com/instana/nodejs

## Overview

##### Main Components
- Traditional Tracing:
– @instana/collector: This is the core package used in server-based environments.
- Serverless Environment Components:
– @instana/aws-fargate
– @instana/aws-lambda
– @instana/google-cloud-run
– @instana/azure-container-services
– Also include @instana/serverless-collector for other serverless scenarios.
- Shared and Supporting Libraries:
– Packages like “core,” “autoprofile,” “collector,” “metrics-util,” “opentelemetry-exporter,” “opentelemetry-sampler,” “shared-metrics,” etc.
– These provide underlying support (such as low-level instrumentation, metrics processing, and native addon support) that feed into both server-based and serverless tracer packages.

##### Relationships & Interactions
- Dependency relationships between the “core” or “shared” packages and the higher-level tracer packages. For example, illustrate that @instana/collector, aws-fargate, and others rely on common utilities found in “core” or “metrics-util.”

##### CI/CD, Testing, and Tooling
- A separate section or side-notes for build and test infrastructure (GitHub Actions, Tekton pipelines, husky hooks, eslint, prettier configurations, etc.).
- That deployment artifacts (for instance, Docker images in the dockerfile-examples folder) integrate with instructional/example apps that demonstrate real-world usage.

##### Architectural Patterns & Design Principles
- Use a “monorepo” pattern where multiple inter-related packages maintain shared configurations and common tooling.
- Separation between the core instrumentation logic (handled in packages such as “collector” and “core”) and the environment-specific wrappers (like aws-lambda or google-cloud-run).
- Integration points with native addons (see the autoprofile package, binary executables in bin/, and native dependency packs) that optimize performance by interfacing with Node’s underlying systems.

## Diagram (Mermaid)

```mermaid
flowchart TD
    repo["Instana Node.js Monorepo"]:::container
    instrumentedApp["Instrumented Application"]:::app

    %% Instrumented Application invoking tracer packages
    instrumentedApp -->|"instruments"| instanaCollector
    instrumentedApp -->|"instruments"| awsFargate
    instrumentedApp -->|"instruments"| awsLambda
    instrumentedApp -->|"instruments"| googleCloudRun
    instrumentedApp -->|"instruments"| azureContainer
    instrumentedApp -->|"instruments"| serverlessCollector

    %% Traditional Tracing Domain
    subgraph "Traditional Tracing Domain"
        instanaCollector["@instana/collector"]:::service
    end

    %% Serverless Environment Domain
    subgraph "Serverless Environment Domain"
        awsFargate["@instana/aws-fargate"]:::serverless
        awsLambda["@instana/aws-lambda"]:::serverless
        googleCloudRun["@instana/google-cloud-run"]:::serverless
        azureContainer["@instana/azure-container-services"]:::serverless
        serverlessCollector["@instana/serverless-collector"]:::serverless
    end

    %% Shared Libraries Domain
    subgraph "Shared Libraries Domain"
        coreUtilities["Core Utilities"]:::shared
        autoprofile["Autoprofile"]:::shared
        metricsUtil["Metrics Util"]:::shared
        otelExporter["OpenTelemetry Exporter"]:::shared
        otelSampler["OpenTelemetry Sampler"]:::shared
        sharedMetrics["Shared Metrics"]:::shared
    end

    %% Dependency relationships between tracer packages and shared libraries
    instanaCollector -->|"depends"| coreUtilities
    instanaCollector -->|"depends"| metricsUtil
    instanaCollector -->|"depends"| otelExporter
    instanaCollector -->|"depends"| otelSampler

    awsFargate -->|"depends"| coreUtilities
    awsFargate -->|"depends"| metricsUtil
    awsLambda -->|"depends"| coreUtilities
    awsLambda -->|"depends"| metricsUtil
    googleCloudRun -->|"depends"| coreUtilities
    googleCloudRun -->|"depends"| metricsUtil
    azureContainer -->|"depends"| coreUtilities
    azureContainer -->|"depends"| metricsUtil
    serverlessCollector -->|"depends"| coreUtilities
    serverlessCollector -->|"depends"| metricsUtil

    %% External Cloud Integrations
    awsFargate -->|"integrates"| awsCloud["AWS Cloud"]:::cloud
    awsLambda -->|"integrates"| awsCloud
    googleCloudRun -->|"integrates"| googleCloud["Google Cloud"]:::cloud
    azureContainer -->|"integrates"| azureCloud["Azure Cloud"]:::cloud

    %% CI/CD & Testing Infrastructure
    subgraph "CI/CD & Testing"
        GHActions["GitHub Actions"]:::infrastructure
        Tekton["Tekton Pipelines"]:::infrastructure
        Husky["Husky Hooks"]:::infrastructure
    end

    %% CI/CD builds and tests all monorepo packages
    GHActions -->|"builds-tests"| repo
    Tekton -->|"builds-tests"| repo
    Husky -->|"builds-tests"| repo

    %% Docker Images and Deployment Artifacts
    dockerImages["Docker Images & Deployment Artifacts"]:::infrastructure
    dockerImages -->|"deploys"| exampleApps

    %% Example Applications
    exampleApps["Example Applications"]:::example

    %% Representation: Monorepo feeds components (for visual grouping)
    repo --> instanaCollector
    repo --> awsFargate
    repo --> coreUtilities

    %% Click Events
    click repo "https://github.com/instana/nodejs/blob/main/."

    click instanaCollector "https://github.com/instana/nodejs/tree/main/packages/collector"
    click awsFargate "https://github.com/instana/nodejs/tree/main/packages/aws-fargate"
    click awsLambda "https://github.com/instana/nodejs/tree/main/packages/aws-lambda"
    click googleCloudRun "https://github.com/instana/nodejs/tree/main/packages/google-cloud-run"
    click azureContainer "https://github.com/instana/nodejs/tree/main/packages/azure-container-services"
    click serverlessCollector "https://github.com/instana/nodejs/tree/main/packages/serverless-collector"
    click coreUtilities "https://github.com/instana/nodejs/tree/main/packages/core"
    click autoprofile "https://github.com/instana/nodejs/tree/main/packages/autoprofile"
    click metricsUtil "https://github.com/instana/nodejs/tree/main/packages/metrics-util"
    click otelExporter "https://github.com/instana/nodejs/tree/main/packages/opentelemetry-exporter"
    click otelSampler "https://github.com/instana/nodejs/tree/main/packages/opentelemetry-sampler"
    click sharedMetrics "https://github.com/instana/nodejs/tree/main/packages/shared-metrics"
    click GHActions "https://github.com/instana/nodejs/tree/main/.github/workflows"
    click Tekton "https://github.com/instana/nodejs/blob/main/.tekton"
    click Husky "https://github.com/instana/nodejs/blob/main/.husky"
    click exampleApps "https://github.com/instana/nodejs/tree/main/example-apps"

    %% Styles
    classDef container fill:#f4cccc,stroke:#000,stroke-width:2px;
    classDef service fill:#c9daf8,stroke:#1155cc,stroke-width:2px;
    classDef serverless fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef shared fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
    classDef app fill:#ead1dc,stroke:#b45f06,stroke-width:2px;
    classDef infrastructure fill:#d9d2e9,stroke:#6d9eeb,stroke-width:2px;
    classDef domain fill:#cfe2f3,stroke:#3c78d8,stroke-width:2px;
    classDef example fill:#d0e0e3,stroke:#1155cc,stroke-width:2px;
    classDef cloud fill:#ffe599,stroke:#b45f06,stroke-width:2px;
```
