# felix-andreas/roughly architecture

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

- Interactive diagram: https://gitdiagram.com/felix-andreas/roughly
- Repository: https://github.com/felix-andreas/roughly

## Overview

##### Project type and purpose
- From the README and file tree, we see “Roughly” is an open-source CLI tool and R language server written in Rust, with a complementary VS Code extension (TypeScript) and a documentation site (Astro + Tailwind). Its core functions are formatting, linting, diagnostics, completions, indexing, and LSP-based editor integration.

##### File structure
- Top level:
- Cargo.toml / src/…: Rust code for CLI subcommands (`fmt`, `check`, `server`) and two LSP server implementations (`server_async_lsp.rs`, `server_tower_lsp.rs`).
- client/: VS Code extension in TypeScript—`extension.ts`, package.json, images.
- docs/: Static documentation site built with Astro/Tailwind—source in docs/src, content in docs/content.
- scripts/: Build‐helper scripts (e.g., `get_node_types.py`).
- tests/: Snapshot and integration tests for formatting and indexing.
- Patterns:
- CLI entrypoint (`main.rs`) delegates to submodules (`format.rs`, `diagnostics.rs`, `completions.rs`, etc.).
- LSP servers implement the Language Server Protocol over JSON-RPC.
- VS Code extension spawns the CLI/LSP binary and connects via stdio.

##### README for additional insights
- Key features: formatter, linter, diagnostics, completions, indexing.
- Installation & usage: CLI commands and VS Code extension settings.
- Architecture hints: bundled CLI in extension, ability to pass custom args, nightly Rust requirement.

a. Main components
- Roughly CLI binary (Rust)
– Formatter module
– Linter/Diagnostics module
– Indexer & Completion module
– Config loader
- LSP Server (Rust)
– Async LSP (tower-lsp)
– JSON-RPC transport
- VS Code Extension (TypeScript)
– Language client (vscode-languageclient)
– Commands & settings
- Documentation Site (Astro + Tailwind) – optional for runtime
- Tests & CI (snapshot tests, justfile, flake.nix)
b. Relationships & interactions
- VS Code Extension ←→ LSP Server via stdin/stdout (JSON-RPC)
- CLI “fmt”/“check” subcommands invoke Rust modules directly
- LSP Server calls same Rust modules under the hood for formatting, diagnostics, completions
- Tests import modules or run CLI commands and compare snapshots
- Documentation site reads configuration/content but does not interact at runtime
c. Architectural patterns & principles
- Modular Rust code: single binary with subcommand pattern (structopt/clap)
- LSP design: separation between protocol layer and core logic
- Extension-client pattern: thin client that delegates work to a robust backend
- Reproducible builds via Nix (flake.nix) and justfile
d. Key technologies
- Rust + clap/structopt, tower-lsp, serde_json
- TypeScript + VS Code extension API, bun/npm
- Astro, Tailwind CSS for docs
- Nix, just, Python build scripts

##### Final advice
- Don’t omit the dual role of the binary (standalone CLI vs. LSP server)
- Extension settings and bundling step (bun run package)
- Detail how tests hook into the formatter module for snapshot testing

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Rust Core
    subgraph "Rust Core"
        direction TB
        Main["main.rs"]:::rust
        CLI["Roughly CLI Binary"]:::rust
        CLI -->|entrypoint| Main
        CLI -->|definitions| CLIdef["cli.rs"]:::rust
        CLI -->|uses| Format["Formatter Module"]:::rust
        CLI -->|uses| Diagnostics["Linter/Diagnostics Module"]:::rust
        Diagnostics -->|fast checks| FastDiag["fast.rs"]:::rust
        Diagnostics -->|syntax checks| SyntaxDiag["syntax.rs"]:::rust
        Diagnostics -->|unused checks| UnusedDiag["unused.rs"]:::rust
        CLI -->|uses| Completions["Completion Module"]:::rust
        CLI -->|uses| Index["Indexing Module"]:::rust
        CLI -->|loads| Config["Configuration Loader"]:::rust
        CLI -->|helper| Dev["Development Server Helper"]:::rust
        Library["Shared Lib & Utilities"]:::rust
        Library --> Lib["lib.rs"]:::rust
        Library --> Utils["utils.rs"]:::rust
        Library --> Tree["tree.rs"]:::rust
        LSPAsync["Async LSP Server"]:::rust
        LSPTower["Tower LSP Server"]:::rust
        LSPAsync -->|handles formatting & diagnostics| Format
        LSPAsync --> Diagnostics
        LSPTower -->|handles formatting & diagnostics| Format
        LSPTower --> Diagnostics
    end

    %% VS Code Extension
    subgraph "VS Code Extension"
        direction TB
        Ext["extension.ts"]:::ts
        Settings["package.json"]:::ts
        Images["images/"]:::ts
        Ext -->|spawn CLI| CLI
        Ext -->|JSON-RPC over stdio| LSPAsync
    end

    %% Documentation Site
    subgraph "Documentation Site"
        direction TB
        ConfigAstro["astro.config.ts"]:::docs
        DocsSrc["docs/src/"]:::docs
        Content["docs/content/"]:::docs
        ConfigTailwind["tailwind.config.ts"]:::docs
        PackageDocs["package.json"]:::docs
        DocsSite["Astro + Tailwind Site"]:::docs
        DocsSite --> ConfigAstro
        DocsSite --> ConfigTailwind
        DocsSite --> DocsSrc
        DocsSite --> Content
        DocsSite --> PackageDocs
    end

    %% Tests & CI
    subgraph "Tests & CI"
        direction TB
        TestFmt["test_format.rs"]:::test
        TestIdx["test_index.rs"]:::test
        Snap["snapshots/"]:::test
        Scripts["get_node_types.py"]:::ci
        CI["justfile / flake.nix / flake.lock"]:::ci
        Tests["Snapshot & Integration Tests"]:::test
        Tests --> TestFmt
        Tests --> TestIdx
        Tests --> Snap
    end

    %% Styles
    classDef rust fill:#e0ffe0,stroke:#099909;
    classDef ts fill:#e0e0ff,stroke:#000999;
    classDef docs fill:#f0f0f0,stroke:#999999;
    classDef test fill:#ffe0e0,stroke:#994400;
    classDef ci fill:#fff0e0,stroke:#999400;

    %% Click Events
    click Main "https://github.com/felix-andreas/roughly/blob/main/src/main.rs"
    click CLIdef "https://github.com/felix-andreas/roughly/blob/main/src/cli.rs"
    click Format "https://github.com/felix-andreas/roughly/blob/main/src/format.rs"
    click Diagnostics "https://github.com/felix-andreas/roughly/blob/main/src/diagnostics.rs"
    click FastDiag "https://github.com/felix-andreas/roughly/blob/main/src/diagnostics/fast.rs"
    click SyntaxDiag "https://github.com/felix-andreas/roughly/blob/main/src/diagnostics/syntax.rs"
    click UnusedDiag "https://github.com/felix-andreas/roughly/blob/main/src/diagnostics/unused.rs"
    click Completions "https://github.com/felix-andreas/roughly/blob/main/src/completions.rs"
    click Index "https://github.com/felix-andreas/roughly/blob/main/src/index.rs"
    click Config "https://github.com/felix-andreas/roughly/blob/main/src/config.rs"
    click Dev "https://github.com/felix-andreas/roughly/blob/main/src/dev.rs"
    click Lib "https://github.com/felix-andreas/roughly/blob/main/src/lib.rs"
    click Utils "https://github.com/felix-andreas/roughly/blob/main/src/utils.rs"
    click Tree "https://github.com/felix-andreas/roughly/blob/main/src/tree.rs"
    click LSPAsync "https://github.com/felix-andreas/roughly/blob/main/src/server_async_lsp.rs"
    click LSPTower "https://github.com/felix-andreas/roughly/blob/main/src/server_tower_lsp.rs"
    click Ext "https://github.com/felix-andreas/roughly/blob/main/client/src/extension.ts"
    click Settings "https://github.com/felix-andreas/roughly/blob/main/client/package.json"
    click Images "https://github.com/felix-andreas/roughly/tree/main/client/images/"
    click ConfigAstro "https://github.com/felix-andreas/roughly/blob/main/docs/astro.config.ts"
    click DocsSrc "https://github.com/felix-andreas/roughly/tree/main/docs/src/"
    click Content "https://github.com/felix-andreas/roughly/tree/main/docs/content/"
    click ConfigTailwind "https://github.com/felix-andreas/roughly/blob/main/docs/tailwind.config.ts"
    click PackageDocs "https://github.com/felix-andreas/roughly/blob/main/docs/package.json"
    click TestFmt "https://github.com/felix-andreas/roughly/blob/main/tests/test_format.rs"
    click TestIdx "https://github.com/felix-andreas/roughly/blob/main/tests/test_index.rs"
    click Snap "https://github.com/felix-andreas/roughly/tree/main/tests/snapshots/"
    click Scripts "https://github.com/felix-andreas/roughly/blob/main/scripts/get_node_types.py"
    click CI "https://github.com/felix-andreas/roughly/tree/main/justfile"
```
