# semenishchev/lamada architecture

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

- Interactive diagram: https://gitdiagram.com/semenishchev/lamada
- Repository: https://github.com/semenishchev/lamada

## Overview

##### Project Type and Purpose
- This is a multi-module JVM framework (library/tool) for executing code remotely via Java functional interfaces (lambdas).
- Core “lamada” module provides the API, serialization, bytecode‐transformation (ASM) and abstractions (Sender, RemoteTargetManager).
- Three transport implementations live in sibling modules: redis‐impl, nats‐impl, netty‐impl.

##### File-structure Analysis
- Top‐level Gradle multi-project:
- build.gradle.kts, settings.gradle.kts (defines subprojects)
- src/… (core library)
- redis-impl/, nats-impl/, netty-impl/ (each with its own build.gradle.kts)
- Core library packages:
- asm/ (lambda bytecode correction & reconstruction)
- context/ (ExecutionContext, InvocationResult)
- defaults/ (FunctionalDistributedObject)
- serialization/ (Kryo setup, serializers, instantiators)
- sender/ (LoopbackSender)
- util/ (helpers, logging)
- DistributedExecutor, RemoteTargetManager, InstructionCommunicator, ObjectStub/Factory
- Implementation modules provide concrete Sender + RemoteTargetManager (e.g. RedisImplementation).

a. Main Components
- Application Code (your domain objects & lambdas)
- Core Lamada API
- DistributedExecutor
- DistributedObject / FunctionalDistributedObject
- ObjectStubFactory
- Serialization Pipeline
- ProjectKryo
- SimpleSerializers, ReferenceResolver
- ASM Pipeline
- LambdaReconstructor, LambdaCorrector
- Transport Abstractions
- Sender interface
- RemoteTargetManager interface
- Implementations (plugin modules)
- RedisImplementation (uses JedisPool, Redis queues)
- NatsImplementation
- NettyImplementation
- External Services
- Redis server
- NATS broker
- Raw TCP / Netty endpoints
- Loopback (in-process)
- LoopbackSender / LoopbackRemoteTargetManager

b. Relationships & Data Flow
1. App invokes DistributedExecutor.run()/runMethod()
2. Core serializes lambda + args via Kryo serializers
3. ASM utilities rewrite bytecode for remote invocation
4. InstructionCommunicator packages instruction
5. Sender.send() → pushes to transport (e.g., Redis list or pub/sub)
6. RemoteTargetManager on target JVM receives instruction
7. ExecutionContext unmarshals, invokes target method on DistributedObject stub
8. Result/exception serialized and sent back via Sender
9. Local side CompletableFuture completes

c. Architectural Patterns
- Plugin pattern: abstract Sender/RemoteTargetManager + multiple implementations
- Separation of concerns: API, serialization, bytecode transformation, transport
- Factory for stubs (ObjectStubFactory)
- Sync barrier via executor.sync() for consistent object registration
- Loopback for testing

d. Key Technologies
- Kotlin DSL Gradle multi-project build
- ASM for bytecode manipulation
- Kryo for serialization
- Jedis (Redis), Netty, NATS client libraries

##### Detail-Level
- Class‐grouping where helpful (e.g., list key classes under “Serialization”).
- Plugin hook (Sender & RemoteTargetManager interfaces) and how each implementation satisfies it.
- Sync() registration phase as a separate pre-execution step.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Application Layer
    App["Application Code"]:::core

    %% Core API
    subgraph "Core API"
        DE["DistributedExecutor"]:::core
        DO["DistributedObject"]:::core
        FDO["FunctionalDistributedObject"]:::core
        OSF["ObjectStubFactory"]:::core
        OS["ObjectStub"]:::core
        SE["StaticExecutor"]:::core
        IC["InstructionCommunicator"]:::core
    end

    %% Serialization Pipeline
    subgraph "Serialization"
        PK["ProjectKryo"]:::core
        SS["SimpleSerializers"]:::core
        RR["ReferenceResolver"]:::core
        SR["SerializationResult"]:::core
        PCI["ProjectClassInstantiator"]:::core
        SCS["SuperclassSerializer"]:::core
        SLK["SlfKryoLogger"]:::core
    end

    %% ASM Pipeline
    subgraph "ASM"
        LC["LambdaCorrector"]:::core
        LR["LambdaReconstructor"]:::core
    end

    %% Transport Abstractions
    subgraph "Transport Abstractions"
        S["Sender (interface)"]:::core
        RTM["RemoteTargetManager (interface)"]:::core
    end

    %% Loopback
    subgraph "Loopback"
        LBS["LoopbackSender"]:::loopback
        LBRTM["LoopbackRemoteTargetManager"]:::loopback
    end

    %% Plugin Implementations
    subgraph "Transport Implementations"
        RI["RedisImplementation"]:::transport
        RExec["RedisExecutor"]:::transport
        VE["VirtualExecutor"]:::transport
        NI["NatsImplementation"]:::transport
        NtI["NettyImplementation"]:::transport
    end

    %% External Services
    subgraph "External Services"
        RS["Redis Server"]:::external
        NB["NATS Broker"]:::external
        NE["Netty Endpoint"]:::external
    end

    %% Flows
    App -->|"run()/runMethod()"| DE
    DE -->|"sync() registration"| SE
    DE -->|"serialize & transform"| PK
    PK --> SS
    PK --> RR
    SS --> SR
    PK --> PCI
    PK --> SCS
    PK --> SLK
    PK --> LC
    LC --> LR
    LR --> IC
    IC --> S
    S --> RI
    S --> NI
    S --> NtI
    S --> LBS

    RI -->|"push instruction"| RS
    NI -->|"publish instruction"| NB
    NtI -->|"send instruction"| NE
    LBS --> LBRTM

    RS -->|"poll instruction"| VE
    NB -->|"subscribe instruction"| NI
    NE -->|"receive instruction"| NtI

    VE -->|"receive & execute"| RTM
    LBRTM -->|"receive & execute"| RTM

    RTM --> EC[ExecutionContext]:::core
    EC --> IR[InvocationResult]:::core
    IR --> PK
    PK --> S
    S --> DE

    EC -->|"invoke on stub"| FDO

    %% Click Events
    click DE "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/DistributedExecutor.java"
    click DO "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/DistributedObject.java"
    click FDO "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/defaults/FunctionalDistributedObject.java"
    click OSF "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/ObjectStubFactory.java"
    click IC "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/InstructionCommunicator.java"
    click RTM "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/RemoteTargetManager.java"
    click LBRTM "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/LoopbackRemoteTargetManager.java"
    click PK "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/serialization/ProjectKryo.java"
    click SS "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/serialization/SimpleSerializers.java"
    click RR "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/serialization/ReferenceResolver.java"
    click SR "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/serialization/SerializationResult.java"
    click LR "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/asm/LambdaReconstructor.java"
    click LC "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/asm/LambdaCorrector.java"
    click LBS "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/sender/LoopbackSender.java"
    click EC "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/context/ExecutionContext.java"
    click IR "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/context/InvocationResult.java"
    click RI "https://github.com/semenishchev/lamada/blob/master/redis-impl/src/main/java/cc/olek/lamada/redis/RedisImplementation.java"
    click RExec "https://github.com/semenishchev/lamada/blob/master/redis-impl/src/main/java/cc/olek/lamada/redis/RedisExecutor.java"
    click VE "https://github.com/semenishchev/lamada/blob/master/redis-impl/src/main/java/cc/olek/lamada/redis/VirtualExecutor.java"
    click OS "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/ObjectStub.java"
    click SE "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/StaticExecutor.java"
    click PCI "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/serialization/ProjectClassInstantiator.java"
    click SCS "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/serialization/SuperclassSerializer.java"
    click SLK "https://github.com/semenishchev/lamada/blob/master/src/main/java/cc/olek/lamada/util/SlfKryoLogger.java"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000
    classDef transport fill:#90EE90,stroke:#000
    classDef external fill:#FFA500,stroke:#000
    classDef loopback fill:#D3D3D3,stroke:#000
```
