> ## Documentation Index
> Fetch the complete documentation index at: https://noorle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Architecture Overview

> Understanding Noorle's layered architecture and host-based routing

Noorle uses a **layered architecture** with **host-based routing** to manage multiple services within a unified platform. This design allows different interfaces (Web UI, REST API, MCP Gateway, Agent Gateway) to coexist seamlessly.

## Host-Based Routing

Noorle routes requests to different services based on the hostname:

```mermaid theme={null}
graph TD
    LB["Load Balancer / Request Router"]
    LB --> Console["console.*<br/>(Web UI)"]
    LB --> API["api.*<br/>(Admin REST)"]
    LB --> MCP["mcp-{id}.*<br/>(MCP Gateway)"]
    LB --> Agent["agent-{id}.*<br/>(A2A Gateway)"]
```

### Virtual Hosts

| Host                    | Service       | Purpose                                                | Protocol       |
| ----------------------- | ------------- | ------------------------------------------------------ | -------------- |
| `console.noorle.com`    | Console       | Web UI for managing gateways, agents, and capabilities | HTTP/HTTPS     |
| `api.noorle.com`        | Admin API     | REST endpoints for account/agent/capability management | HTTP/REST      |
| `mcp-{id}.noorle.com`   | MCP Gateway   | Exposes capabilities via MCP protocol                  | MCP (SSE/HTTP) |
| `agent-{id}.noorle.com` | Agent Gateway | A2A protocol for agent-to-agent communication          | A2A            |

## Layered Architecture

Noorle's architecture consists of three layers:

```mermaid theme={null}
graph TB
    subgraph Interface["Interface Layer"]
        Console["Web UI<br/>console.noorle.com"]
        AdminAPI["REST API<br/>api.noorle.com"]
        McpGateway["MCP Gateway<br/>mcp-{id}.noorle.com"]
        AgentGateway["Agent Gateway<br/>agent-{id}.noorle.com"]
    end

    subgraph Application["Application Layer"]
        Auth["Authentication<br/>& Session Mgmt"]
        CapService["Capability<br/>Service"]
        AgentRuntime["Agent Runtime<br/>& Orchestration"]
        KnowledgeService["Knowledge &<br/>Memory Services"]
    end

    subgraph Platform["Platform Services"]
        PluginRuntime["Plugin Runtime<br/>WebAssembly Sandbox"]
        CapabilityStore["Capability Store<br/>DB + Cache"]
        LLMIntegration["LLM Integration<br/>Multi-Provider"]
        Storage["Object Storage"]
    end

    subgraph Data["Data Layer"]
        Database["PostgreSQL"]
        Cache["Redis<br/>Caching"]
        VectorDB["Vector DB"]
    end

    Console --> Auth
    AdminAPI --> Auth
    McpGateway --> Auth
    AgentGateway --> Auth

    Auth --> CapService
    Auth --> AgentRuntime
    Auth --> KnowledgeService

    CapService --> PluginRuntime
    CapService --> CapabilityStore
    AgentRuntime --> LLMIntegration
    AgentRuntime --> CapService
    KnowledgeService --> Storage

    CapabilityStore --> Database
    CapabilityStore --> Cache
    KnowledgeService --> VectorDB
    LLMIntegration --> Cache
```

### Layer Responsibilities

**Interface Layer**

* Routes incoming requests to appropriate handlers
* Manages session state and WebSocket connections
* Handles protocol translation (HTTP/REST → MCP, A2A)

**Application Layer**

* Unified authentication across all services
* Capability service: manages builtin, plugin, and connector access
* Agent runtime: executes agents with tool integration
* Memory and knowledge services: vector search, embeddings, conversational memory

**Platform Services**

* Plugin runtime: secure WebAssembly sandbox for custom tools
* Capability store: registry and metadata for all tools
* LLM integration: model selection and prompt routing across multiple providers
* Object storage: plugin artifacts, knowledge bases, exports

**Data Layer**

* PostgreSQL: relational data (agents, gateways, capabilities, etc.)
* Redis: caching and session management
* Vector database: embeddings for semantic search

## Request Flow Example

How a request flows through the system:

```mermaid theme={null}
graph TD
    A["User Request"]
    A --> B["Load Balancer<br/>host-based routing"]
    B --> C1["console.noorle.com"]
    B --> C2["api.noorle.com"]
    B --> C3["mcp-{id}.noorle.com"]

    C1 --> D1["Console Service"]
    D1 --> E1["UI View Rendering"]

    C2 --> D2["Admin API"]
    D2 --> F1["REST Handler"]

    F1 --> Auth1["Auth Middleware"]
    Auth1 --> Auth2["Auth Service"]

    C3 --> D3["MCP Gateway"]
    D3 --> F2["Tool Listing/Execution"]
    F2 --> Auth3["Auth Middleware"]
    Auth3 --> Cap["Capability Service"]
    Cap --> G1["Plugin Runtime"]
    Cap --> G2["Built-in Services"]
    Cap --> G3["Connector Services"]
```

## Key Architectural Decisions

### Unified Capability Model

All capabilities (builtin, plugin, connector) are accessed through the same `CapabilityService`, ensuring consistent tool discovery and execution regardless of type.

### Protocol Translation

MCP Gateway and Agent Gateway translate between their respective protocols (MCP, A2A) and the internal capability model, providing a clean separation of concerns.

### Multi-Tenancy by Design

Account-based resource isolation is enforced at the service layer. Every operation includes an `account_id` to prevent cross-account data leaks.

### Stateless Services

Gateway services are stateless and can be horizontally scaled. Conversation state, memory, and session data are persisted in Redis and PostgreSQL.

## Performance Characteristics

* **Latency**: Sub-100ms capability access via multi-tier caching
* **Concurrency**: Async runtime supports thousands of concurrent connections
* **Storage**: PostgreSQL handles millions of capabilities; vector database scales semantic search
* **Cost Control**: Optional work budgets constrain execution costs at runtime

***

Next: Explore [Use Cases](/learn/use-cases) to see Noorle in action.