# dynge/norgmaestro architecture

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

- Interactive diagram: https://gitdiagram.com/dynge/norgmaestro
- Repository: https://github.com/dynge/norgmaestro

## Overview

##### Project Type and Purpose
- That NorgMaestro is an LSP server designed to support Norg files.
- The purpose is to receive LSP messages from an editor/IDE client, process them via specialized handlers, and respond using defined RPC message formats.
- Emphasis should be on the messaging protocol, modular handlers, parsing subsystem, and the overall server orchestration.

##### Major Components
A. Language Server Core:
- Central component encapsulated in files like LanguageServer.cs and LanguageServerState.cs.
- Responsible for receiving LSP messages, managing server state, and coordinating the various subcomponents.

B. Method Handlers:
- Represented by the Methods folder (e.g., CompletionHandler.cs, HoverHandler.cs, InitializeHandler.cs).
- Each handler implements IMessageHandler to process specific LSP requests such as completion, hover, document save events, etc.
- HandlerFactory that determines which handler to use for an incoming message.

C. Parsing Subsystem:
- Located in the Parser directory.
- Components include NorgParser.cs and FileUtil.cs to help process Norg files.
- A subcomponent in the TS subdirectory (Treesitter.cs) indicates that Treesitter is used to parse the language’s grammar or syntax trees.

D. RPC Communication Layer:
- Found under the Rpc directory, which includes message classes for CallHierarchy, Completion, DidSave, and others.
- RpcMessageWriter.cs is an important connection point for serializing and sending responses.
- This layer abstracts the communication over the LSP protocol.

E. Entry Point:
- Program.cs which bootstraps the LanguageServer and sets up orchestrations possibly including dependency injection, initialization, etc.

F. Testing Suite:
- The tests folder (NorgMaestro.Tests) contains unit tests for critical components like the HandlerFactory and the RPC reader/writer implementations.
- Even if not part of the runtime architecture, tests verify that component interactions are correct.

##### Relationships and Data Flow
- The Client (IDE/editor) sends LSP messages to the LanguageServer.
- The LanguageServer (core) receives these messages and consults the HandlerFactory to route the message to an appropriate Method Handler.
- Each Method Handler processes the message (often using the Parser for syntactic analysis if needed) and then interacts with the RPC layer to send back responses.
- The RPC modules encapsulate the structure for requests/responses and handle the encoding/decoding of messages.
- Overall, the flow is: Client → LanguageServer Core → Handler Factory → Specific Method Handler → (Optional) Parser → RPC Layer → Client.

##### Architectural Patterns & Design Principles
- Modularity: Different directories for methods, parser, and RPC indicate separation of concerns.
- Factory Pattern: The HandlerFactory dynamically routes messages to the correct handler.
- Layered Architecture: An outer communication layer (RPC) interfaces with inner processing layers (handlers and parser).
- Interface-Driven Design: Use of interfaces (e.g., IMessageHandler) ensures handlers can be swapped or extended easily.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    A["Client (Editor/IDE)"]:::client
    B["Language Server Core"]:::core
    C["Entry Point (Program.cs)"]:::entry
    D["RPC Communication Layer"]:::rpc
    E["Handler Factory"]:::handler
    F["Method Handlers"]:::handler
    G["Parser Subsystem"]:::parser
    H["Treesitter"]:::parser
    I["Testing Suite"]:::test

    %% Connections
    A -->|"sends LSP messages"| B
    C -->|"bootstraps"| B
    B -->|"routes messages to"| E
    E -->|"dispatches to"| F
    F -->|"invokes parsing if needed"| G
    G -->|"uses"| H
    F -->|"produces response via"| D
    B -->|"sends responses via"| D
    D -->|"returns responses to"| A
    I -->|"tests components like"| E

    %% Click Events
    click B "https://github.com/dynge/norgmaestro/blob/main/NorgMaestro.Server/LanguageServer.cs"
    click E "https://github.com/dynge/norgmaestro/blob/main/NorgMaestro.Server/Methods/HandlerFactory.cs"
    click F "https://github.com/dynge/norgmaestro/tree/main/NorgMaestro.Server/Methods"
    click G "https://github.com/dynge/norgmaestro/tree/main/NorgMaestro.Server/Parser"
    click H "https://github.com/dynge/norgmaestro/blob/main/NorgMaestro.Server/Parser/TS/Treesitter.cs"
    click D "https://github.com/dynge/norgmaestro/tree/main/NorgMaestro.Server/Rpc"
    click C "https://github.com/dynge/norgmaestro/blob/main/NorgMaestro.Server/Program.cs"
    click I "https://github.com/dynge/norgmaestro/blob/main/NorgMaestro.Tests"

    %% Styles
    classDef client fill:#f9c,stroke:#333,stroke-width:2px;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px;
    classDef handler fill:#afa,stroke:#333,stroke-width:2px;
    classDef parser fill:#fed,stroke:#333,stroke-width:2px;
    classDef rpc fill:#eef,stroke:#333,stroke-width:2px;
    classDef entry fill:#fdd,stroke:#333,stroke-width:2px;
    classDef test fill:#ddd,stroke:#333,stroke-width:2px;
```
