# foliagecp/sdk architecture

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

- Interactive diagram: https://gitdiagram.com/foliagecp/sdk
- Repository: https://github.com/foliagecp/sdk

## Overview

##### Main Components
- Backend Services:
– Graph Management & CRUD: Modules located under the “embedded/graph” directory (subfolders include “common”, “crud”, “debug”, “graphql”, “jpgql”, “search”, and “triggerfunc”) represent the core of the graph database operations. This includes low-level and high-level CRUD operations, debugging utilities (with dot/graphml exporters), and GraphQL interfaces.
– State Functionality: The “statefun” folder contains logic for caching, logging, mediators, and plugin integration (e.g., JavaScript plugins). This represents infrastructure-level functionalities needed for runtime state management and orchestration.
– Client SDK: The “clients/go” directory shows the Go client’s database interactions. It demonstrates how applications use the SDK to communicate with underlying graph functionality.
- External/Supporting Components:
– NATS Integration: Components in “embedded/nats” and relevant configuration and tests in the “tests” directories indicate the platform’s reliance on NATS Jetstream, key/value storage, and messaging.
– Testing & Deployment: The “tests” directory (with its “basic”, “distributed”, and “e2e” subfolders) along with Docker-compose files reveal a containerized, orchestrated environment for validating both basic and distributed use cases.
– Documentation & Conventions: The “docs” directory gives additional context about features, plugins, performance measures, and architectural conventions.

##### Relationships and Interactions
- The client applications (from “clients/go”) interact with the backend graph operations and stateful services.
- The backend is segmented into different modules: CRUD functions, debugging tools, GraphQL endpoints, and query languages (JPGQL). They collaborate to manage the graph database and expose its functionality to external services.
- NATS Jetstream and related messaging components serve as the communication layer between various system modules and test environments.
- State management (in “statefun”) orchestrates the interactions and logging across different modules, ensuring robust runtime behavior and plugin support.

##### Architectural Patterns and Design Principles
- Modular Design: Each functional area (graph CRUD, debugging, GraphQL, plugins) lives in its own subdirectory, promoting separation of concerns.
- Integration via Messaging: NATS Jetstream integration underlines an event-driven architecture, critical for distributed systems.
- Plugin Architecture: The presence of JavaScript plugins in “statefun/plugins/js” suggests extensibility.
- Containerized Deployment: The use of Docker and Docker Compose for testing reflects a microservice-like container architecture.

##### Final Recommendations
- Avoid oversimplification—each architectural element (from embedded modules to testing environments) should be represented with clear labels and interaction directions.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Foliage Core Platform
    subgraph "Foliage Core Platform"
        %% Graph Engine Module
        subgraph "Graph Engine"
            CRUD["Graph CRUD Operations"]:::backend
            Debug["Graph Debugging Tools"]:::backend
            GraphQL["GraphQL Interface"]:::backend
            JPGQL["JPGQL Query Support"]:::backend
            Search["Graph Search Module"]:::backend
            Trigger["Trigger Functions"]:::backend
        end
        %% State Management Module
        subgraph "State Management & Infrastructure"
            State["State Management & Infrastructure"]:::state
            JSPlugin["JavaScript Plugin Integration"]:::state
        end
    end

    %% External Components
    ClientSDK["Client SDK (Go)"]:::client
    NATS["NATS Integration"]:::external
    Tests["Testing & Deployment Environment"]:::external
    Docs["Documentation & Architectural Conventions"]:::external
    Frontend["Frontend (React, TypeScript)"]:::frontend

    %% Interactions
    ClientSDK -->|"calls API"| CRUD
    ClientSDK -->|"calls API"| State
    State -->|"integrates_Plugins"| JSPlugin
    CRUD -->|"publishes_Events"| NATS
    GraphQL -->|"emits_Messages"| NATS
    State -->|"syncs_State"| NATS
    Tests -->|"tests_GraphEngine"| CRUD
    Tests -->|"tests_StateManagement"| State
    Docs -->|"documents_GraphEngine"| CRUD
    Docs -->|"documents_StateManagement"| State
    Frontend -->|"interacts_With"| ClientSDK

    %% Click Events for Component Mapping
    click CRUD "https://github.com/foliagecp/sdk/tree/main/embedded/graph/crud"
    click Debug "https://github.com/foliagecp/sdk/tree/main/embedded/graph/debug"
    click GraphQL "https://github.com/foliagecp/sdk/tree/main/embedded/graph/graphql"
    click JPGQL "https://github.com/foliagecp/sdk/tree/main/embedded/graph/jpgql"
    click Search "https://github.com/foliagecp/sdk/tree/main/embedded/graph/search"
    click Trigger "https://github.com/foliagecp/sdk/tree/main/embedded/graph/triggerfunc"
    click State "https://github.com/foliagecp/sdk/tree/main/statefun"
    click JSPlugin "https://github.com/foliagecp/sdk/tree/main/statefun/plugins/js"
    click ClientSDK "https://github.com/foliagecp/sdk/tree/main/clients/go"
    click NATS "https://github.com/foliagecp/sdk/tree/main/embedded/nats"
    click Tests "https://github.com/foliagecp/sdk/tree/main/tests"
    click Docs "https://github.com/foliagecp/sdk/tree/main/docs"

    %% Styling Classes
    classDef backend fill:#f9c,stroke:#333,stroke-width:2px;
    classDef state fill:#ff9,stroke:#333,stroke-width:2px;
    classDef client fill:#9f9,stroke:#333,stroke-width:2px;
    classDef external fill:#9ff,stroke:#333,stroke-width:2px;
    classDef frontend fill:#fc9,stroke:#333,stroke-width:2px;
```
