# julep-ai/julep architecture

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

- Interactive diagram: https://gitdiagram.com/julep-ai/julep
- Repository: https://github.com/julep-ai/julep

## Overview

##### Main Components
- Agents API – This is the core backend service that manages agents, tasks, workflows, and orchestrates complex operations. Note that it is organized in its own “agents-api” directory with subdirectories for activities, routers, queries, and workers.
- Integrations Service – This service handles third-party integrations (e.g., with Brave, Email, Cloudinary, etc.). Its structure under “integrations-service” indicates a similar modular microservice approach.
- CLI and SDK Clients – The CLI tool (in the “cli” folder) and SDK libraries (both Python and Node.js) represent the client components through which developers interact with the backend.
- Gateway – A service (under “gateway”) that likely serves as a reverse proxy, managing incoming requests and possibly enforcing security, authentication, or routing them to the correct backend component.
- Blob Store and Memory Store – Storage systems for handling files and persistent state (look at “blob-store” and “memory-store” directories). They might store large binary objects or support caching and session data.
- Scheduler – Found under “scheduler”; this component likely manages timed or event-based job execution and might integrate with Temporal given the presence of temporal-related profiles in deployment.
- Monitoring – Support components (under “monitoring”) that include Docker Compose configurations for Grafana and Prometheus, indicating real-time observability and metrics collection.
- Documentation, Typespecs, and Schemas – Though not part of the runtime, these provide important insight into APIs and the expected formats (e.g., “typespec” and “schemas” directories).

##### Relationships and Interactions
- Client Layer:
– End users (developers or automated systems) interact with Julep via the CLI and SDKs.
– They submit task definitions and commands that trigger workflows.
- API & Gateway:
– Requests from clients flow into the Gateway, which then dispatches them to either the Agents API or the Integrations Service.
– The Agents API handles core processing (orchestrating tasks, managing state, and handling workflow logic).
- Internal Communication:
– The Agents API likely communicates with the integrations service (and possibly the blob-store and memory-store) to run tools or persist data.
– The Scheduler orchestrates task executions (possibly triggering processes in the worker components under Agents API or Integrations Service).
- Data Storage & Monitoring:
– Memory Store, Blob Store, and a database (as indicated by numerous migration files) act as persistent stores.
– Monitoring setups gather metrics, track execution statuses, and feed logs back to an operations dashboard.
- External API Calls:

##### Architectural Patterns and Design Principles
- Microservices: The clear separation between agents, integrations, gateway, storage, and scheduling indicates a microservice architecture.
- Modular Organization: Each service is organized in a self-contained directory, following principles such as “separation of concerns” and “single responsibility.”
- Service Communication: Likely using RESTful APIs between services with defined schemas (provided in the “typespec” and “schemas” folders).
- Asynchronous & Parallel Processing: The workflow engine supports parallel tasks and asynchronous processing (e.g., “parallelism” in workflow YAML specifications).
- Containerization & Deployment: With Docker Compose files across services (for agents-api, integrations-service, gateway, blob-store, memory-store, etc.), container orchestration is central to deployment.
- Observability: Integration with monitoring tools (Prometheus, Grafana) suggests that logging, metrics, and observability are key network components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        CLI["Julep CLI Client"]:::client
        NodeSDK["Node SDK"]:::sdk
        PythonSDK["Python SDK"]:::sdk
    end

    %% API Gateway Layer
    subgraph "API Gateway Layer"
        Gateway["Gateway (Reverse Proxy)"]:::gateway
    end

    %% Core Services Layer
    subgraph "Core Services"
        AgentsAPI["Agents API (Task orchestration, state management)"]:::core
        IntegrationsService["Integrations Service (Third-party integrations)"]:::core
        Scheduler["Scheduler (Job execution and orchestration)"]:::core
    end

    %% Data & Storage Layer
    subgraph "Data & Storage Layer"
        BlobStore["Blob Store (Binary data storage)"]:::storage
        MemoryStore["Memory Store (Cache and session data)"]:::storage
        Database["Migration Database (Persistent storage)"]:::storage
    end

    %% Observability & Monitoring Layer
    subgraph "Observability & Monitoring"
        Monitoring["Monitoring (Grafana, Prometheus)"]:::monitor
    end

    %% External Integrations
    subgraph "External Integrations"
        External["External Tools (e.g., Brave, Discord)"]:::external
    end

    %% Documentation & Schemas
    subgraph "Documentation & Schemas"
        Documentation["Documentation"]:::docs
        Typespec["Typespecs"]:::docs
        Schemas["Schemas"]:::docs
    end

    %% Connections from Client Layer to Gateway
    CLI -->|"sends commands"| Gateway
    NodeSDK -->|"sends API requests"| Gateway
    PythonSDK -->|"sends API requests"| Gateway

    %% Connections from Gateway to Core Services
    Gateway -->|"routes to"| AgentsAPI
    Gateway -->|"routes to"| IntegrationsService
    Gateway -->|"routes to"| Scheduler

    %% Internal Communication within Core Services
    Scheduler -->|"orchestrates tasks"| AgentsAPI

    %% Connections from Agents API to Data Stores
    AgentsAPI -->|"persists data"| BlobStore
    AgentsAPI -->|"persists data"| MemoryStore
    AgentsAPI -->|"persists data"| Database

    %% External API interactions
    AgentsAPI ---|"calls external"| External
    IntegrationsService ---|"calls external"| External

    %% Monitoring connections
    AgentsAPI -->|"metrics"| Monitoring
    IntegrationsService -->|"metrics"| Monitoring
    Scheduler -->|"metrics"| Monitoring
    BlobStore -->|"health check"| Monitoring
    MemoryStore -->|"health check"| Monitoring
    Database -->|"health check"| Monitoring

    %% Click Events
    click CLI "https://github.com/julep-ai/julep/tree/dev/cli/"
    click NodeSDK "https://github.com/julep-ai/julep/tree/dev/sdks/node-sdk/"
    click PythonSDK "https://github.com/julep-ai/julep/tree/dev/sdks/python-sdk/"
    click Gateway "https://github.com/julep-ai/julep/tree/dev/gateway/"
    click AgentsAPI "https://github.com/julep-ai/julep/tree/dev/agents-api/"
    click IntegrationsService "https://github.com/julep-ai/julep/tree/dev/integrations-service/"
    click Scheduler "https://github.com/julep-ai/julep/tree/dev/scheduler/"
    click BlobStore "https://github.com/julep-ai/julep/tree/dev/blob-store/"
    click MemoryStore "https://github.com/julep-ai/julep/tree/dev/memory-store/"
    click Monitoring "https://github.com/julep-ai/julep/tree/dev/monitoring/"
    click Documentation "https://github.com/julep-ai/julep/tree/dev/documentation/"
    click Typespec "https://github.com/julep-ai/julep/tree/dev/typespec/"
    click Schemas "https://github.com/julep-ai/julep/tree/dev/schemas/"

    %% Styles
    classDef client fill:#f9d6a5,stroke:#d17f10,stroke-width:2px;
    classDef sdk fill:#fce5cd,stroke:#d17f10,stroke-width:2px;
    classDef gateway fill:#cfe2f3,stroke:#6d9eeb,stroke-width:2px;
    classDef core fill:#d9ead3,stroke:#6aa84f,stroke-width:2px;
    classDef storage fill:#ead1dc,stroke:#b854a4,stroke-width:2px;
    classDef monitor fill:#d0e0e3,stroke:#6aa5ac,stroke-width:2px;
    classDef external fill:#fff2cc,stroke:#bf9000,stroke-width:2px;
    classDef docs fill:#f4cccc,stroke:#c00,stroke-width:2px;
```
