# aws-greengrass/aws-greengrass-nucleus architecture

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

- Interactive diagram: https://gitdiagram.com/aws-greengrass/aws-greengrass-nucleus
- Repository: https://github.com/aws-greengrass/aws-greengrass-nucleus

## Overview

##### Project type and purpose
- This is a backend‐only, device‐side orchestration runtime (AWS Greengrass Nucleus) written in Java.
- Purpose: manage and monitor “services” (components) on IoT devices—handling configuration, lifecycle, inter‐process communication (IPC), deployments, and cloud interactions (IoT Jobs, MQTT, S3/ECR, etc.).

##### File structure
- Top‐level modules (under `src/main/java/com/aws/greengrass`):
- config (hierarchical key‐value store with watchers)
- dependency (injection framework)
- lifecyclemanager (service FSM, start/stop logic)
- componentmanager (artifact download, dependency resolution, recipe parsing)
- deployment (IoT Jobs integration, deployment queue, activators, bootstrapping)
- provisioning & easysetup (device onboarding)
- ipc (EventStream RPC server & modules)
- mqttclient & iot (publish/subscribe to AWS IoT Core)
- status & telemetry (fleet/status reporting, metrics aggregation)
- security & authorization (token management, policy enforcement)
- util (OS abstraction, systemd/Winsw/procd, platform controllers)
- Scripts (`scripts/greengrass.*`) and conf (`conf/recipe.yaml`) support systemd or procd launch.
- Build and CI/config files: `pom.xml`, `.github/workflows`, checkstyle, license, README variants.

##### Readme insights
- Emphasizes four layers: config, dependency DI, lifecyclemanager, util.
- Project is a mash‐up of “make,” pub/sub, key‐value store with continuous adaptation.

a. Local Runtime (Nucleus) – a single process hosting:
- Configuration Store (config)
- Dependency Injector (dependency)
- Lifecycle Manager (lifecyclemanager)
- Component Manager (componentmanager)
- Deployment Service (deployment + IoT Jobs client)
- IPC Server (IPCEventStreamService)
- MQTT Client (awsIoT client)
- Status & Telemetry Agents
- Security & Authorization Module
- EasySetup / Provisioning Modules
b. External Services & Dependencies
- AWS IoT Core (MQTT)
- AWS IoT Jobs (Deployment control plane)
- Artifact Repositories (S3, Docker/ECR, Greengrass Repo)
- System Service Controllers (systemd, procd, Winsw)
c. Data flows & interactions
1. On boot, EasySetup/Provisioning registers device → writes config
2. Deployment Service polls/subscribes to IoT Jobs → on “new job”: download recipe → Component Manager downloads artifacts via S3/ECR → resolve dependencies → update local store → Lifecycle Manager orchestrates start/stop of component processes
3. Components and built-in services communicate via IPC server (publish/subscribe channels)
4. Config store watchers notify dependent modules when config changes
5. Telemetry & Status modules collect state, push metrics/status back to cloud (IoT Core)
6. Security module validates tokens/requests for IPC, network access
7. Util/orchestration modules handle OS‐level process control, permissions, restart logic
d. Architectural patterns & principles
- Dependency Injection (inversion of control for service objects)
- Finite-State Machine for lifecycle phases
- Publish/Subscribe for IPC and config notification
- Modular layering (core nucleus, built-in services, extensions/plugins)
- Pluggable Artifact Downloaders (S3, Docker, Greengrass Repo)
- Cloud-edge decoupling via IoT Jobs & MQTT
e. Technologies & frameworks
- Java 11+
- Maven build
- AWS SDK v2 (IoT, S3, STS)
- EventStream RPC (IPC)
- JNA (native calls)
- systemd / procd / Winsw wrappers

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% OS Layer
    subgraph "OS Layer"
        OSController["OS Controller"]:::os
    end

    %% Edge Runtime Core
    subgraph "Edge Runtime Core"
        DI["Dependency Injector"]:::core
        ConfigStore["Config Store"]:::core
        Lifecycle["Lifecycle Manager"]:::core
        ComponentMgr["Component Manager"]:::core
        Deployment["Deployment Service"]:::core
        IPC["IPC Server"]:::core
        MQTTClient["MQTT Client"]:::core
        Telemetry["Telemetry Agent"]:::core
        Status["Status Service"]:::core
        AuthModule["Authorization Module"]:::core
        EasySetup["EasySetup / Provisioning"]:::core
        Util["Utility Layer"]:::core
    end

    %% Built-in Services
    subgraph "Built-in Services"
        ConfigIPC["Config Store IPC Service"]:::builtin
        LifeIPC["Lifecycle IPC Service"]:::builtin
        MQTTProxy["MQTT Proxy IPC Service"]:::builtin
        PubSubIPC["Pub/Sub IPC Service"]:::builtin
    end

    %% Artifact Downloaders
    subgraph "Artifact Downloaders"
        BuiltinAD["Builtins"]:::plugin
        DockerAD["Docker"]:::plugin
    end

    %% Deployment Extensions
    subgraph "Deployment Extensions"
        Activators["Deployment Activators"]:::core
        Bootstrap["Deployment Bootstrapping"]:::core
    end

    %% IPC Modules
    subgraph "IPC Modules"
        IPCModules["IPC Modules"]:::core
    end

    %% Cloud Services
    subgraph "Cloud"
        AWSIoT["AWS IoT Core (MQTT)"]:::cloud
        IoTJobs["AWS IoT Jobs"]:::cloud
        S3ECR["Artifact Repositories (S3/ECR)"]:::cloud
    end

    %% Dependencies
    DI -->|instantiates| ConfigStore
    DI -->|instantiates| Lifecycle
    DI -->|instantiates| ComponentMgr
    DI -->|instantiates| Deployment
    DI -->|instantiates| IPC
    DI -->|instantiates| MQTTClient
    DI -->|instantiates| Telemetry
    DI -->|instantiates| Status
    DI -->|instantiates| AuthModule
    DI -->|instantiates| EasySetup
    DI -->|instantiates| Util

    ConfigStore -->|notifies| Lifecycle
    ConfigStore -->|notifies| ComponentMgr
    EasySetup -->|writes config| ConfigStore

    Deployment -->|uses| IoTJobs
    IoTJobs -->|publishes jobs| Deployment
    Deployment -->|downloads artifacts| S3ECR
    Deployment -->|triggers| ComponentMgr
    ComponentMgr -->|resolves| BuiltinAD
    ComponentMgr -->|resolves| DockerAD
    ComponentMgr -->|signals| Lifecycle
    Lifecycle -->|controls| OSController

    IPC -->|provides endpoints| ConfigIPC
    IPC -->|provides endpoints| LifeIPC
    IPC -->|provides endpoints| MQTTProxy
    IPC -->|provides endpoints| PubSubIPC
    IPC -->|loads| IPCModules

    MQTTClient <-->|MQTT messages| AWSIoT
    Telemetry -->|publishes metrics| AWSIoT
    Status -->|publishes status| AWSIoT

    AuthModule -->|validates| IPC
    Util -->|orchestrates processes| OSController

    %% Click Events
    click ConfigStore "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/config"
    click ConfigIPC "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/builtin/services/configstore"
    click DI "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/dependency"
    click Lifecycle "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/lifecyclemanager"
    click LifeIPC "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/builtin/services/lifecycle"
    click ComponentMgr "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/componentmanager"
    click BuiltinAD "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/componentmanager/builtins"
    click DockerAD "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/componentmanager/plugins/docker"
    click Deployment "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/deployment"
    click Activators "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/deployment/activator"
    click Bootstrap "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/deployment/bootstrap"
    click IPC "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/ipc/IPCEventStreamService.java"
    click IPCModules "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/ipc/modules"
    click MQTTClient "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/mqttclient"
    click MQTTProxy "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/builtin/services/mqttproxy"
    click PubSubIPC "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/builtin/services/pubsub"
    click Telemetry "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/telemetry/TelemetryAgent.java"
    click Status "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/status/FleetStatusService.java"
    click AuthModule "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/authorization/AuthorizationModule.java"
    click AuthIPC "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/authorization/AuthorizationIPCAgent.java"
    click EasySetup "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/easysetup/GreengrassSetup.java"
    click Provisioning "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/src/main/java/com/aws/greengrass/provisioning/ProvisioningPluginFactory.java"
    click Util "https://github.com/aws-greengrass/aws-greengrass-nucleus/tree/main/src/main/java/com/aws/greengrass/util"
    click Script1 "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/scripts/greengrass.service.template"
    click Script2 "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/scripts/greengrass.service.procd.template"
    click Recipe "https://github.com/aws-greengrass/aws-greengrass-nucleus/blob/main/conf/recipe.yaml"

    %% Styles
    classDef core fill:#e0f7fa,stroke:#006064,color:#000
    classDef builtin fill:#ffecb3,stroke:#ff6f00,color:#000
    classDef plugin fill:#e1bee7,stroke:#6a1b9a,color:#000
    classDef cloud fill:#c8e6c9,stroke:#2e7d32,color:#000
    classDef os fill:#ffcdd2,stroke:#c62828,color:#000
```
