Architecture

The LegionEdge Platform is built on a microservices architecture designed for scalability, resilience, and extensibility. This page describes the major components and how they interact.

High-Level Overview

                          ┌─────────────────────┐
                          │     Clients          │
                          │  (SDK, Dashboard,    │
                          │   CLI, Third-party)  │
                          └─────────┬────────────┘
                                    │
                                    ▼
                          ┌─────────────────────┐
                          │    API Gateway       │
                          │  (Auth, Rate Limit,  │
                          │   Routing, TLS)      │
                          └─────────┬────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                   │
                 ▼                  ▼                   ▼
          ┌─────────────┐  ┌──────────────┐  ┌──────────────┐
          │ Auth Service │  │ Project Svc  │  │ Resource Svc │
          │ (OAuth, JWT, │  │ (CRUD, Envs, │  │ (Allocation, │
          │  API Keys)   │  │  Teams)      │  │  Lifecycle)  │
          └──────┬───────┘  └──────┬───────┘  └──────┬───────┘
                 │                 │                  │
                 └─────────────────┼──────────────────┘
                                   │
                          ┌────────▼────────┐
                          │   Event Bus     │
                          │  (Async Events, │
                          │   Webhooks)     │
                          └────────┬────────┘
                                   │
                 ┌─────────────────┼─────────────────┐
                 ▼                 ▼                  ▼
          ┌─────────────┐  ┌──────────────┐  ┌──────────────┐
          │   Nokuva    │  │    Tovac     │  │   Foltrac    │
          │ (AI Agents) │  │ (Data/Memory)│  │ (Infra/Guard)│
          └─────────────┘  └──────────────┘  └──────────────┘

Core Components

API Gateway

The gateway is the single entry point for all client requests. It handles:

• TLS termination and request validation
• Authentication -- verifies API keys and JWT tokens before forwarding requests
• Rate limiting -- per-key and per-organization rate limits with sliding window counters
• Request routing -- routes to the appropriate internal service based on the URL path
• Observability -- emits structured logs, metrics, and distributed traces for every request

Auth Service

Manages all identity and access operations:

• OAuth 2.0 authorization code flow with PKCE
• API key issuance, rotation, and revocation
• JWT token signing and validation
• Session management and SSO federation
• RBAC policy evaluation

Project Service

Handles the lifecycle of projects and their associated metadata:

• Project CRUD operations
• Environment management (development, staging, production)
• Team membership and role assignment
• Project-level settings and secrets

Resource Service

Manages resources allocated to projects:

• Resource provisioning and deprovisioning
• Health monitoring and status tracking
• Scaling and configuration updates
• Cost tracking and quota enforcement

Event Bus

An internal message broker that decouples services:

• Publishes domain events (e.g., project.created, resource.scaled)
• Delivers events to webhook endpoints
• Powers the real-time event stream API
• Guarantees at-least-once delivery with configurable retry policies

Data Flow

A typical API request follows this path:

1. The client sends an HTTPS request to api.legionedge.com/v2.
2. The API gateway authenticates the request and checks rate limits.
3. The gateway routes the request to the appropriate service.
4. The service processes the request, persists state, and publishes events.
5. The event bus dispatches events to registered webhook endpoints.
6. The service returns a response through the gateway to the client.

Integration Architecture

Product integrations (Nokuva, Tovac, Foltrac) communicate with the platform through the event bus for asynchronous operations and through internal gRPC endpoints for synchronous calls. This design allows each product to evolve independently while sharing a common identity and access control layer.

// SDK usage abstraction across products
import { LegionEdge } from "@legionedge/sdk";

const client = new LegionEdge({ apiKey: process.env.LEGIONEDGE_API_KEY! });

// Platform API
const project = await client.projects.get("proj_abc");

// Nokuva integration (via platform)
const agents = await client.integrations.nokuva.agents.list({
  projectId: project.id,
});

Next Steps

• Learn how authentication works across the platform.
• Explore the data models that underpin each service.