# adevinta/zoe architecture

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

- Interactive diagram: https://gitdiagram.com/adevinta/zoe
- Repository: https://github.com/adevinta/zoe

## Overview

##### Main Components
The system has three main modules that should be prominently featured:

a. zoe-cli (Command Interface)
- Entry point for user interactions
- Command handling and parsing
- Configuration management

b. zoe-core (Core Functionality)
- Base functions for Kafka operations
- JSON utilities
- Polling and producing capabilities

c. zoe-service (Service Layer)
- Runner implementations (Kubernetes, Lambda, Local)
- Secret management
- Expression handling
- Storage operations

##### External Integration Points
Integration with:
- Kafka clusters
- Kubernetes clusters
- AWS Lambda
- Secret management systems (AWS Secrets Manager, Strongbox)

**┌─ User Interface Layer ─────────────────────┐**
- Zoe CLI                       │
- (Commands, Config, Aliases, Topics)       │
- ┤
- Zoe Core                      │
- (Kafka Operations, JSON Utils, Functions) │
- ┤
- Zoe Service                   │
- (Runners, Secrets, Storage, Config)     │
- ┤
- Execution Layer                  │
- ┌─────────┐  ┌──────────┐  ┌──────────┐  │
- Local   │  │Kubernetes│  │  Lambda  │  │
- ┘  └──────────┘  └──────────┘  │
- ┘

##### Key Relationships

a. Control Flow:
- CLI → Core → Service → Runners → Kafka
- Config management flow
- Secret resolution flow

b. Data Flow:
- Kafka data consumption/production paths
- Configuration loading paths
- Runner execution paths

##### Important Details

a. Runner Architecture:
- How different runners (Kubernetes, Lambda, Local) interact
- Parallel execution capabilities
- Scaling mechanisms

b. Configuration Management:
- Config initialization flow
- Environment handling
- Default configurations

c. Security Layer:
- Secret management integration
- Authentication flows
- Access control

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph UI["User Interface Layer"]
        CLI["Zoe CLI"]:::cli
        CMD["Command Handlers"]:::cmd
        CONF["Configuration Management"]:::conf
        CLI --> CMD
        CLI --> CONF
    end

    subgraph Core["Core Layer"]
        CORE["Core Module"]:::core
        JSON["JSON Utilities"]:::json
        KOP["Kafka Operations"]:::kafka
        POLL["Polling"]:::poll
        PROD["Producing"]:::prod
        ADM["Admin"]:::admin
        
        CORE --> JSON
        CORE --> KOP
        KOP --> POLL
        KOP --> PROD
        KOP --> ADM
    end

    subgraph Service["Service Layer"]
        SVC["Service Module"]:::service
        SEC["Secret Management"]:::secret
        EXP["Expression Handling"]:::exp
        STR["Storage Operations"]:::storage
        
        SVC --> SEC
        SVC --> EXP
        SVC --> STR
    end

    subgraph Execution["Execution Layer"]
        direction TB
        KUB["Kubernetes Runner"]:::runner
        LAM["Lambda Runner"]:::runner
        LOC["Local Runner"]:::runner
    end

    subgraph External["External Systems"]
        direction TB
        KAFKA[("Kafka Clusters")]:::external
        K8S[("Kubernetes")]:::external
        AWS[("AWS Lambda")]:::external
        SECRETS[("Secret Stores")]:::external
    end

    UI --> Core
    Core --> Service
    Service --> Execution
    
    KUB --> K8S
    LAM --> AWS
    Execution --> KAFKA
    SEC --> SECRETS

    %% Component Mappings
    click CLI "https://github.com/adevinta/zoe/blob/master/zoe-cli/src/commands/main.kt"
    click CORE "https://github.com/adevinta/zoe/blob/master/zoe-core/src/main.kt"
    click SVC "https://github.com/adevinta/zoe/blob/master/zoe-service/src/service.kt"
    click KUB "https://github.com/adevinta/zoe/blob/master/zoe-service/src/runners/kubernetes.kt"
    click LAM "https://github.com/adevinta/zoe/blob/master/zoe-service/src/runners/lambda.kt"
    click LOC "https://github.com/adevinta/zoe/blob/master/zoe-service/src/runners/local.kt"
    click SEC "https://github.com/adevinta/zoe/blob/master/zoe-service/src/secrets/secrets.kt"
    click EXP "https://github.com/adevinta/zoe/blob/master/zoe-service/src/expressions/expressions.kt"
    click STR "https://github.com/adevinta/zoe/blob/master/zoe-service/src/storage/storage.kt"
    click CONF "https://github.com/adevinta/zoe/blob/master/zoe-cli/src/config/config.kt"
    click KOP "https://github.com/adevinta/zoe/tree/master/zoe-core/src/functions"
    click JSON "https://github.com/adevinta/zoe/blob/master/zoe-core/src/utils/json.kt"
    click CMD "https://github.com/adevinta/zoe/tree/master/zoe-cli/src/commands"
    click POLL "https://github.com/adevinta/zoe/blob/master/zoe-core/src/functions/poll.kt"
    click PROD "https://github.com/adevinta/zoe/blob/master/zoe-core/src/functions/produce.kt"
    click ADM "https://github.com/adevinta/zoe/blob/master/zoe-core/src/functions/admin.kt"

    classDef cli fill:#2196F3,stroke:#1565C0,color:white
    classDef cmd fill:#1976D2,stroke:#1565C0,color:white
    classDef conf fill:#1565C0,stroke:#0D47A1,color:white
    classDef core fill:#00BCD4,stroke:#0097A7,color:white
    classDef json fill:#00ACC1,stroke:#0097A7,color:white
    classDef kafka fill:#26C6DA,stroke:#0097A7,color:white
    classDef service fill:#4CAF50,stroke:#388E3C,color:white
    classDef secret fill:#43A047,stroke:#2E7D32,color:white
    classDef exp fill:#66BB6A,stroke:#388E3C,color:white
    classDef storage fill:#81C784,stroke:#388E3C,color:white
    classDef runner fill:#FF9800,stroke:#F57C00,color:white
    classDef external fill:#9E9E9E,stroke:#616161,color:white
    classDef poll fill:#26A69A,stroke:#00796B,color:white
    classDef prod fill:#26A69A,stroke:#00796B,color:white
    classDef admin fill:#26A69A,stroke:#00796B,color:white
```
