# swyddfa/esbonio architecture

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

- Interactive diagram: https://gitdiagram.com/swyddfa/esbonio
- Repository: https://github.com/swyddfa/esbonio

## Overview

##### Project Type & Purpose
- This part of the project implements a Language Server for Sphinx, whose goal is to aid the writing process by providing code completions, diagnostics, “go to definition/implementation” commands, and other IDE features. It integrates tightly with Sphinx’s build processes to support live previews and incremental builds.

##### Key Components
a. Core Language Server:
– This is initialized in the entry point (esbonio/__main__.py) and is responsible for starting the server.
– It handles LSP communication (receiving requests from VSCode or other client editors) and delegates requests to the appropriate internal modules.

b. Server CLI & Configuration:
– The CLI scripts (for instance, in esbonio/server/cli.py and _configuration.py) handle startup parameters, configuration management, and environment setup.

c. Features & Modules:
– Break out the individual “feature” components within the esbonio/server directory. Include components such as:
- Directives: Responsible for handling Sphinx directives (under server/features/directives).
- Roles: For resolving roles and completions (server/features/roles).
- Sphinx Manager: Coordinates Sphinx build integration (server/features/sphinx_manager, including client.py, manager.py, etc.).
- MYST support: Managed through the server/features/myst submodule.
- Preview Manager: Handles live preview functionality (server/features/preview_manager).
- Project Manager: Deals with project-specific data and state (server/features/project_manager).
- Additional support modules like logging and event handling (e.g., server/events.py and server/features/log.py).

d. Sphinx Agent (if applicable):
– Though it appears as a separate module (esbonio/sphinx_agent), it tightly couples with the main server to manage asynchronous operations such as updating diagnostics in near-real-time.

e. Supporting Utilities:
– Components such as the logging module, constants, and configuration modules (e.g., common/log.ts in the overall project context, though here focus is on the Python backend).

##### Relationships & Interactions
- The Language Client (for example, the VSCode extension or any LSP-compatible editor) sends requests/notifications to the Language Server.
- The Core Language Server routes these requests to the relevant feature/module (for example, completion requests might be handled by the directives or roles module).
- There is a clear dependency from the “server/cli.py” and configuration modules to the overall initialization of the system.
- Feature modules might interact with each other locally (for example, the sphinx_manager can invoke logging or even interact with the preview manager to push build updates).
- An external interaction is with the Sphinx build system, which is invoked or monitored by the server to guarantee that documentation builds are up to date.

##### Architectural Patterns & Design Principles
- A Modular/Microkernel Architecture: The core language server handles communication and dispatches to self-contained feature modules.
- Plugin/Extension Design: The language server’s functionality is divided into distinct subsystems (e.g., directives, roles, preview management) so that each can evolve independently or be extended.
- Separation of Concerns: Distinct separation is maintained between initialization/CLI/configuration, core LSP responsibilities, and feature-specific logic.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Nodes
    LClient("Language Client"):::external
    ServerCore("Language Server Core"):::core
    CLIConf("CLI & Configuration"):::feature
    Directives("Directives Feature Module"):::feature
    Roles("Roles Feature Module"):::feature
    SphinxManager("Sphinx Manager (Build Integration)"):::feature
    MYST("MYST Support"):::feature
    Preview("Preview Manager (Live Preview)"):::feature
    Project("Project Manager"):::feature
    LogEvent("Logging & Event Support"):::feature
    SphinxAgent("Sphinx Agent (Async Operations)"):::feature

    %% External Interaction
    LClient -->|"LSPRequests/Responses"| ServerCore

    %% Initialization dependency
    CLIConf -->|"InitConfig"| ServerCore

    %% Internal delegation from core to features
    ServerCore -->|"Delegates"| Directives
    ServerCore -->|"Delegates"| Roles
    ServerCore -->|"Delegates"| SphinxManager
    ServerCore -->|"Delegates"| MYST
    ServerCore -->|"Delegates"| Preview
    ServerCore -->|"Delegates"| Project
    ServerCore -->|"Delegates"| LogEvent
    ServerCore -->|"Manages"| SphinxAgent

    %% Inter-module interaction
    SphinxManager -->|"TriggersUpdate"| Preview
    SphinxManager -->|"Logs"| LogEvent

    %% Click Events
    click ServerCore "https://github.com/swyddfa/esbonio/blob/develop/lib/esbonio/esbonio/__main__.py"
    click CLIConf "https://github.com/swyddfa/esbonio/blob/develop/lib/esbonio/esbonio/server/cli.py"
    click CLIConf "https://github.com/swyddfa/esbonio/blob/develop/lib/esbonio/esbonio/server/_configuration.py"
    click Directives "https://github.com/swyddfa/esbonio/tree/develop/lib/esbonio/esbonio/server/features/directives"
    click Roles "https://github.com/swyddfa/esbonio/tree/develop/lib/esbonio/esbonio/server/features/roles"
    click SphinxManager "https://github.com/swyddfa/esbonio/tree/develop/lib/esbonio/esbonio/server/features/sphinx_manager"
    click MYST "https://github.com/swyddfa/esbonio/tree/develop/lib/esbonio/esbonio/server/features/myst"
    click Preview "https://github.com/swyddfa/esbonio/tree/develop/lib/esbonio/esbonio/server/features/preview_manager"
    click Project "https://github.com/swyddfa/esbonio/tree/develop/lib/esbonio/esbonio/server/features/project_manager"
    click LogEvent "https://github.com/swyddfa/esbonio/blob/develop/lib/esbonio/esbonio/server/features/log.py"
    click LogEvent "https://github.com/swyddfa/esbonio/blob/develop/lib/esbonio/esbonio/server/events.py"
    click SphinxAgent "https://github.com/swyddfa/esbonio/tree/develop/lib/esbonio/esbonio/sphinx_agent"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef feature fill:#d4edda,stroke:#155724,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#f8d7da,stroke:#721c24,stroke-width:2px;
```
