# montoyan877/lambda-running architecture

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

- Interactive diagram: https://gitdiagram.com/montoyan877/lambda-running
- Repository: https://github.com/montoyan877/lambda-running

## Overview

##### Project Type & Purpose
- Lambda Running is a tool designed to allow developers to locally run and test AWS Lambda functions. It supports both a web-based UI mode and an interactive CLI mode.
- The README and file layout emphasize zero-configuration testing, custom event injection and Lambda layers support – all aimed at simulating real AWS Lambda environments for rapid iteration.

##### Key Components
- CLI & Entry Points:
- Binaries (bin/lambda-run.js, bin/ui-start.js) initiate different modes.
- The CLI commands (interactive mode) and direct command invocation are supported via src/commands.
- Backend Core Engine:
- Lambda Runner (src/lambda-runner.js) is at the heart of the simulation, actually invoking the Lambda functions.
- Event Store (src/event-store.js) is responsible for tracking and logging events during local execution.
- Config Loader (src/config-loader.js) manages environment settings and configurations from .env files and lambda-running.json.
- Layer Resolver (src/layer-resolver.js) handles mapping AWS Lambda layers from the local filesystem (guided by configurations in lambda-running.json and the directory structure in layers/).
- UI Components:
- The UI server (src/ui-server.js) provides backend support to the Vue-based frontend housed in the ui directory.
- The ui folder contains the complete Vue application (with components, router, state management, and assets) that offers a modern web interface for testing and viewing real-time logs and events.
- Supporting Infrastructure:
- Configuration files such as .env.example, .lambdarunignore, and the sample configurations in lambda-running.json that impact scanning, environment loading, and layer mappings.
- Test suites (in tests/) that validate integration, unit functionality, and UI behaviors.
- Documentation (docs/) and examples (examples/) that help users understand and extend the system.

##### Relationships & Interactions
- The CLI commands and UI Mode both kick off by first loading configurations (via src/config-loader.js) which initialize settings such as environment variables and lambda layer paths.
- Once initialized, they call into the Lambda Runner. The runner uses the Event Store to record invocation logs and execution details.
- The Layer Resolver plays a critical role when a Lambda function needs to use a defined layer – mapping the expected AWS layer file structure to the local layer directory.
- In UI mode, the UI server (src/ui-server.js) serves the Vue application found under ui/ and acts as a bridge between the backend simulation engine and the real-time web interface.
- The CLI mode, on the other hand, feeds commands directly to the Lambda Runner and Event Store, displaying results in the terminal.

##### Architectural Patterns & Technologies
- Overall, the architecture adopts a modular design where different concerns (configuration, execution, logging, UI) are clearly separated.
- There is a distinct separation of frontend (Vue-based UI) and backend (command processing, lambda runner) components.
- Patterns such as “configuration loader” and “layer resolver” encapsulate specific responsibilities.
- Key technologies include Node.js (for running backend scripts and CLI commands), Vue along with Vite for the frontend, and support for both JavaScript and TypeScript (as observed in examples/typescript-examples and presence of ts_alias files).

##### Instructing the Principal Software Engineer
– From the CLI/Entry Points to the Config Loader.
– From the Config Loader to both the Lambda Runner and the Layer Resolver.
– From the Lambda Runner to the Event Store.
– From the UI Server to the Vue-based frontend components.
- Annotations or legends where necessary to clarify responsibilities (e.g., “Handles environment configuration”, “Maps local layer directories”).

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Backend Simulation Engine"
        subgraph "CLI & Commands"
            CLI1["bin/lambda-run.js"]:::cli
            CLI2["bin/ui-start.js"]:::cli
            CLI3["src/commands/init.js"]:::cli
        end
        configLoader["Config Loader (src/config-loader.js)"]:::config
        lambdaRunner["Lambda Runner (src/lambda-runner.js)"]:::runner
        eventStore["Event Store (src/event-store.js)"]:::event
        layerResolver["Layer Resolver (src/layer-resolver.js)"]:::layer

        CLI1 --> configLoader
        CLI2 --> configLoader
        CLI3 --> configLoader

        configLoader -->|"invoke"| lambdaRunner
        configLoader -->|"resolve"| layerResolver
        lambdaRunner -->|"log"| eventStore

        subgraph "Supporting Infrastructure"
            cf[".env.example"]:::infra
            cf2["lambda-running.json"]:::infra
            cf3[".lambdarunignore"]:::infra
            tests["Test Suites (tests/)"]:::infra
            docs["Documentation (docs/)"]:::infra
            examples["Examples (examples/)"]:::infra
        end

        cf --- configLoader
        cf2 --- configLoader
        cf3 --- configLoader
        tests --- configLoader
        docs --- configLoader
        examples --- configLoader
    end

    subgraph "Frontend UI"
        uiServer["UI Server (src/ui-server.js)"]:::ui
        vueFrontend["Vue Frontend (ui/)"]:::ui
       
        uiServer -->|"serve"| vueFrontend
        uiServer -->|"initConfig"| configLoader
        uiServer -->|"bridge"| lambdaRunner
    end

click CLI1 "https://github.com/montoyan877/lambda-running/blob/main/bin/lambda-run.js"
click CLI2 "https://github.com/montoyan877/lambda-running/blob/main/bin/ui-start.js"
click CLI3 "https://github.com/montoyan877/lambda-running/blob/main/src/commands/init.js"
click configLoader "https://github.com/montoyan877/lambda-running/blob/main/src/config-loader.js"
click lambdaRunner "https://github.com/montoyan877/lambda-running/blob/main/src/lambda-runner.js"
click eventStore "https://github.com/montoyan877/lambda-running/blob/main/src/event-store.js"
click layerResolver "https://github.com/montoyan877/lambda-running/blob/main/src/layer-resolver.js"
click uiServer "https://github.com/montoyan877/lambda-running/blob/main/src/ui-server.js"
click vueFrontend "https://github.com/montoyan877/lambda-running/tree/main/ui/"
click cf "https://github.com/montoyan877/lambda-running/blob/main/.env.example"
click cf2 "https://github.com/montoyan877/lambda-running/blob/main/lambda-running.json"
click cf3 "https://github.com/montoyan877/lambda-running/blob/main/.lambdarunignore"
click tests "https://github.com/montoyan877/lambda-running/tree/main/tests/"
click docs "https://github.com/montoyan877/lambda-running/tree/main/docs/"
click examples "https://github.com/montoyan877/lambda-running/tree/main/examples/"

classDef cli fill:#f9f,stroke:#333,stroke-width:2px;
classDef config fill:#BBDEFB,stroke:#333,stroke-width:2px;
classDef runner fill:#C8E6C9,stroke:#333,stroke-width:2px;
classDef event fill:#FFCCBC,stroke:#333,stroke-width:2px;
classDef layer fill:#D1C4E9,stroke:#333,stroke-width:2px;
classDef ui fill:#FFF9C4,stroke:#333,stroke-width:2px;
classDef infra fill:#CFD8DC,stroke:#333,stroke-width:2px;
```
