# emcie-co/parlant architecture

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

- Interactive diagram: https://gitdiagram.com/emcie-co/parlant
- Repository: https://github.com/emcie-co/parlant

## Overview

##### Project Type and Purpose
- This is a full-stack AI agent framework (“Parlant”) designed to let developers define conversational AI agents via natural-language guidelines.
- The backend is a Python server exposing REST/WebSocket APIs, the core engine applies guidelines, and the frontend is a React chat widget.
- Key use cases: production chatbots in financial, healthcare, e-commerce, legal domains with guaranteed rule compliance.

##### High-Level File Structure and Architectural Patterns
- Top-level “src/parlant”
- adapters: connectors to databases (JSON file, MongoDB, in-memory), NLP providers (OpenAI, Anthropic, AWS, Azure, HuggingFace, etc.), vector DBs (Chroma).
- api: HTTP/WebSocket endpoints, React chat widget under api/chat.
- core: business logic, guideline matching engine, event emission, NLP helper layers, persistence abstraction, tool integrations.
- bin: CLI entrypoints (client.py, server.py).
- sdk.py: Python client library.
- Tests organized per layer (adapters, api, core, sdk) confirming a modular clean-separation architecture.
- Deployment: Docker in .devcontainer, GitHub Actions CI, build/publish scripts.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        ReactWidget["React Chat Widget"]:::frontend
        SDKClient["SDK Client Library"]:::frontend
        CLITools["CLI Tools"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        APIServer["Backend API Server"]:::api
        AuthMiddleware["Authorization & Security Middleware"]:::api
        AgentAPI["Agent Management API"]:::api
        CannedAPI["Canned Responses API"]:::api
        CapabilitiesAPI["Capabilities API"]:::api
        SessionsWS["Sessions & WebSocket Logger Endpoint"]:::api
    end

    %% Domain Layer
    subgraph "Domain Layer"
        direction TB
        CoreApp["Core Engine Entry & Orchestration"]:::core
        GuidelineEngine["Guideline Matching Engine"]:::core
        MessageGen["Message Generator"]:::core
        PromptResolver["Prompt Builder & Guideline Resolver"]:::core
        EventPub["Event Emission & Publisher"]:::core
        NLPService["NLP Helper Layer & Policies"]:::core
        PersistenceCore["Persistence Abstraction"]:::core
        BackgroundTasks["Background Tasks & Async Utilities"]:::core
        ToolRegistry["Tool Integration Framework"]:::core
        ToolCaller["Custom Tool Caller"]:::core

        subgraph Adapters
            direction TB
            NLPAdapters["NLP Adapters"]:::adapter
            PersistenceAdapters["Persistence Adapters"]:::adapter
            VectorAdapters["Vector Store Adapters"]:::adapter
            LoggerAdapters["Logger Adapters"]:::adapter
        end
    end

    %% Datastores
    subgraph "Datastores"
        direction TB
        DocDB["MongoDB / JSON File"]:::database
        VectorDB["Chroma / In-Memory Vector DB"]:::database
    end

    %% External Services
    subgraph "External Services"
        direction TB
        LLMProviders["LLM Providers"]:::external
        ThirdPartyTools["Third-Party Tools (Plugins)"]:::external
    end

    %% Connections
    User -->|interacts via UI| ReactWidget
    User -->|uses SDK| SDKClient
    User -->|uses CLI| CLITools

    ReactWidget -->|HTTP/WebSocket| APIServer
    SDKClient -->|REST API| APIServer
    CLITools -->|REST API| APIServer

    APIServer -->|passes to| AuthMiddleware
    AuthMiddleware --> AgentAPI
    AuthMiddleware --> CannedAPI
    AuthMiddleware --> CapabilitiesAPI
    AuthMiddleware --> SessionsWS

    SessionsWS -->|logs events| LoggerAdapters

    AgentAPI --> CoreApp
    CannedAPI --> CoreApp
    CapabilitiesAPI --> CoreApp
    SessionsWS --> CoreApp

    CoreApp --> GuidelineEngine
    CoreApp --> MessageGen
    CoreApp --> PromptResolver
    CoreApp --> EventPub
    CoreApp --> NLPService
    CoreApp --> PersistenceCore
    CoreApp --> BackgroundTasks
    CoreApp --> ToolRegistry
    CoreApp --> ToolCaller

    GuidelineEngine --> NLPService
    MessageGen --> NLPService
    PromptResolver --> PersistenceCore

    NLPService --> NLPAdapters
    PersistenceCore --> PersistenceAdapters
    PersistenceCore --> VectorAdapters
    EventPub --> LoggerAdapters
    PersistenceAdapters --> DocDB
    VectorAdapters --> VectorDB
    NLPAdapters --> LLMProviders
    ToolCaller -.-> ThirdPartyTools

    %% Click Events
    click ReactWidget "https://github.com/emcie-co/parlant/tree/develop/src/parlant/api/chat"
    click SDKClient "https://github.com/emcie-co/parlant/blob/develop/src/parlant/sdk.py"
    click CLITools "https://github.com/emcie-co/parlant/tree/develop/src/parlant/bin"
    click APIServer "https://github.com/emcie-co/parlant/blob/develop/src/parlant/api/app.py"
    click AgentAPI "https://github.com/emcie-co/parlant/blob/develop/src/parlant/api/agents.py"
    click AuthMiddleware "https://github.com/emcie-co/parlant/blob/develop/src/parlant/api/authorization.py"
    click CannedAPI "https://github.com/emcie-co/parlant/blob/develop/src/parlant/api/canned_responses.py"
    click CapabilitiesAPI "https://github.com/emcie-co/parlant/blob/develop/src/parlant/api/capabilities.py"
    click SessionsWS "https://github.com/emcie-co/parlant/blob/develop/src/parlant/api/sessions.py"
    click CoreApp "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/application.py"
    click GuidelineEngine "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/engines/alpha/engine.py"
    click MessageGen "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/engines/alpha/message_generator.py"
    click PromptResolver "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/engines/alpha/prompt_builder.py"
    click EventPub "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/emission/event_buffer.py"
    click NLPService "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/nlp/service.py"
    click PersistenceCore "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/persistence/common.py"
    click BackgroundTasks "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/background_tasks.py"
    click ToolRegistry "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/services/tools/service_registry.py"
    click ToolCaller "https://github.com/emcie-co/parlant/blob/develop/src/parlant/core/engines/alpha/tool_calling/tool_caller.py"
    click NLPAdapters "https://github.com/emcie-co/parlant/tree/develop/src/parlant/adapters/nlp"
    click PersistenceAdapters "https://github.com/emcie-co/parlant/tree/develop/src/parlant/adapters/db"
    click VectorAdapters "https://github.com/emcie-co/parlant/tree/develop/src/parlant/adapters/vector_db"
    click LoggerAdapters "https://github.com/emcie-co/parlant/blob/develop/src/parlant/adapters/loggers/websocket.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#000000
    classDef api fill:#E8F5E9,stroke:#2E7D32,color:#000000
    classDef core fill:#FFF3E0,stroke:#EF6C00,color:#000000
    classDef adapter fill:#EDE7F6,stroke:#5E35B1,color:#000000
    classDef database fill:#E8F5E9,stroke:#388E3C,stroke-width:2px,color:#000000
    classDef external fill:#FFEBEE,stroke:#D32F2F,color:#000000
```
