# pherrymason/c3-lsp architecture

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

- Interactive diagram: https://gitdiagram.com/pherrymason/c3-lsp
- Repository: https://github.com/pherrymason/c3-lsp

## Overview

##### Project Type Analysis
This is a Language Server Protocol implementation, which is a specialized type of client-server application that provides language features to IDEs and text editors. The project consists of two main components:
- A server component (written in Go)
- A client component (VSCode extension)

##### Main Components

a) Client Layer:
- VSCode Extension (in /client/vscode)
- Connection to other potential editor clients (extensibility point)

b) Server Core (/server):
- LSP Protocol Handler (/server/internal/lsp/server)
- Project State Management (/server/internal/lsp/project_state)
- Symbol Management System (/server/pkg/symbols)

c) Language Processing:
- AST Processing (/server/internal/lsp/ast)
- CST Processing (/server/internal/lsp/cst)
- Parser System (/server/pkg/parser)

d) Feature Implementations:
- Search System (/server/internal/lsp/search)
- Symbol Table (/server/pkg/symbols_table)
- Document Management (/server/pkg/document)

**[Editor Clients] <---> [LSP Protocol Layer] <---> [C3 Language Server Core]**

**[Source Code] -> [Parser] -> [CST] -> [AST] -> [Symbol Table]**

##### Important Flows to Highlight

a) Document Processing Flow:
- Document changes
- Parse operations
- Symbol indexing
- Diagnostic generation

b) Feature Request Flow:
- Completion requests
- Definition lookup
- Declaration resolution
- Hover information retrieval

Level 1: High-level architecture
- Client-Server communication
- Main system components

Level 2: Server internals
- LSP protocol handling
- Project state management
- Language processing pipeline

Level 3: Feature implementation details
- Symbol resolution
- Search system
- Document management

##### Implementation Details

- Tree-sitter integration for parsing
- Symbol table organization
- Document store structure
- Search system architecture

Remember to:
- Use clear, consistent naming
- Version information handling
- Error handling paths
- Configuration points
- Extension points for future features

## Diagram (Mermaid)

```mermaid
graph TB
    %% Styles
    classDef client fill:#2374ab,color:#fff
    classDef protocol fill:#48a9a6,color:#fff
    classDef core fill:#4caf50,color:#fff
    classDef lang fill:#ff9800,color:#fff
    classDef data fill:#9c27b0,color:#fff
    classDef feature fill:#e91e63,color:#fff

    %% Client Layer
    subgraph Clients
        VSCode["VSCode Extension"]
        OtherEditors["Other Editor Clients"]
    end
    click VSCode "https://github.com/pherrymason/c3-lsp/tree/main/client/vscode"

    %% Protocol Layer
    subgraph Protocol
        LSPHandler["LSP Protocol Handler"]
        ProtocolTransform["Protocol Transformer"]
    end
    click LSPHandler "https://github.com/pherrymason/c3-lsp/tree/main/server/internal/lsp/server"
    click ProtocolTransform "https://github.com/pherrymason/c3-lsp/blob/main/server/internal/lsp/protocol/transformer.go"

    %% Server Core
    subgraph Core
        MainServer["Main Server"]
        ProjectState["Project State Manager"]
        DocManager["Document Manager"]
    end
    click MainServer "https://github.com/pherrymason/c3-lsp/blob/main/server/cmd/lsp/main.go"
    click ProjectState "https://github.com/pherrymason/c3-lsp/tree/main/server/internal/lsp/project_state"
    click DocManager "https://github.com/pherrymason/c3-lsp/tree/main/server/pkg/document"

    %% Language Processing
    subgraph Language
        Parser["Parser System"]
        CST["CST Processor"]
        AST["AST Processor"]
    end
    click Parser "https://github.com/pherrymason/c3-lsp/tree/main/server/pkg/parser"
    click CST "https://github.com/pherrymason/c3-lsp/tree/main/server/internal/lsp/cst"
    click AST "https://github.com/pherrymason/c3-lsp/tree/main/server/internal/lsp/ast"

    %% Data Management
    subgraph Data
        SymbolMgmt["Symbol Management"]
        SymbolTable["Symbol Table"]
        SymbolTrie["Symbol Trie"]
        StdLib["Standard Library"]
    end
    click SymbolMgmt "https://github.com/pherrymason/c3-lsp/tree/main/server/pkg/symbols"
    click SymbolTable "https://github.com/pherrymason/c3-lsp/tree/main/server/pkg/symbols_table"
    click SymbolTrie "https://github.com/pherrymason/c3-lsp/tree/main/server/internal/lsp/symbol_trie"
    click StdLib "https://github.com/pherrymason/c3-lsp/tree/main/server/internal/lsp/stdlib"

    %% Feature Systems
    subgraph Features
        SearchSystem["Search System"]
    end
    click SearchSystem "https://github.com/pherrymason/c3-lsp/tree/main/server/internal/lsp/search"

    %% Relationships
    VSCode --> LSPHandler
    OtherEditors --> LSPHandler
    LSPHandler <--> ProtocolTransform
    ProtocolTransform <--> MainServer
    MainServer --> ProjectState
    MainServer --> DocManager
    
    ProjectState --> Parser
    Parser --> CST
    CST --> AST
    AST --> SymbolTable
    
    DocManager --> SymbolMgmt
    SymbolMgmt --> SymbolTable
    SymbolMgmt --> SymbolTrie
    
    SearchSystem --> SymbolTable
    SearchSystem --> SymbolTrie
    
    StdLib --> SymbolTable
    
    %% Style Applications
    class VSCode,OtherEditors client
    class LSPHandler,ProtocolTransform protocol
    class MainServer,ProjectState,DocManager core
    class Parser,CST,AST lang
    class SymbolMgmt,SymbolTable,SymbolTrie,StdLib data
    class SearchSystem feature
```
