# streetsidesoftware/cspell architecture

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

- Interactive diagram: https://gitdiagram.com/streetsidesoftware/cspell
- Repository: https://github.com/streetsidesoftware/cspell

## Overview

##### Project type and purpose
- This is a monorepo hosting an open-source, code-spell-checker toolchain (“CSpell”) implemented in Node.js/TypeScript.
- It comprises a command-line application (`packages/cspell`), a core library (`packages/cspell-lib`), ancillary libraries (e.g., `cspell-io`, `cspell-glob`, `cspell-trie-lib`, `hunspell-reader`), integrations (e.g., ESLint plugin), tools for dictionary compilation, and a documentation website.

##### File structure
- Top-level: monorepo config (`pnpm-workspace.yaml`, `lerna.json`), CI workflows (`.github/workflows`), scripts, docs, and `packages/` folder.
- Inside `packages/`: each subfolder is an independent npm package with its own `src/`, `tests`, `package.json`.
- There is also a `website/` folder for docs (React/Docusaurus).
- Integration tests live under `integration-tests/`.
- README enumerates main packages and their high-level use cases.

##### README for additional insights
- The README highlights the command-line app, ESLint plugin, dictionaries, I/O, core library, type definitions, tools, trie libraries, and Hunspell reader.
- It calls out how each package fits into the overall spell-checking pipeline.

a. Main components
- **CLI Application** (packages/cspell)
- **Core Library** (packages/cspell-lib)
- **Configuration Loader** (packages/cspell-config-lib)
- **File I/O Module** (packages/cspell-io)
- **File Parsing/Grammar** (packages/cspell-grammar)
- **Glob Matching** (packages/cspell-glob)
- **Dictionary Data**
- Bundled Dictionaries (cspell-bundled-dicts)
- Hunspell Reader (hunspell-reader)
- Trie Builder & Trie Data Structure (cspell-trie-lib, cspell-trie)
- **Suggestion Engine** (packages/cspell-dictionary, parts of cspell-lib)
- **Reporter Layers**
- CLI Reporter (within cspell)
- JSON Reporter (packages/cspell-json-reporter)
- **ESLint Integration** (packages/cspell-eslint-plugin)
- **Dictionary Compiler** (packages/cspell-tools)
- **Community Website** (website/)
- **CI/CD Pipeline** (GitHub Actions under `.github/workflows`)
- **Integration Tests** (integration-tests/)

b. Relationships & interactions
- **CLI App** → loads **config** via Config Loader → uses **Glob** and **File I/O** to locate and read files.
- For each file: **Grammar Parser** extracts text segments → passes text to **Core Library**.
- **Core Library** → loads dictionaries (bundled, Hunspell via Hunspell Reader) → transforms into trie structures via **Trie Lib**.
- **Suggestion Engine** in Core → checks words → returns spelling issues.
- Results → routed to **Reporter** (CLI output or JSON).
- **ESLint Plugin** wraps Core Library as an ESLint rule, emits lint violations.
- **Dictionary Compiler** (cspell-tools) is a standalone procedural tool that uses Trie Builder to produce optimized word lists/trie files.
- **Integration Tests** invoke the CLI with various configs and compare outputs to snapshots.
- **CI/CD** orchestrates lint, unit tests, integration tests, build, and website deployment.

c. Architectural patterns & principles
- **Monorepo Modularization**: each package is an independent module with clear responsibility.
- **Dependency Injection & Service Bus** (cspell-service-bus) for decoupling components.
- **Pipeline Pattern**: file discovery → parsing → validation → reporting.
- **Separation of Concerns**: config, I/O, parsing, dictionary management, suggestion logic, and reporting reside in distinct packages.
- **Pluggability**: supports custom dictionary readers, grammar parsers (RFC for plugins).

d. Key technologies & frameworks
- Node.js, TypeScript, pnpm (workspace), Lerna.
- Testing: Jest, Vitest.
- CI: GitHub Actions.
- Website: Docusaurus (React).
- Build scripts: MJS scripts under `scripts/`.

##### Final advice
- **all essential architectural elements** without over-splitting; group logically.
- Use **consistent naming** matching the package folder names for clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Monorepo Workspace"
        direction TB

        subgraph "Configuration"
            direction TB
            ConfigLoader["Config Loader\n(packages/cspell-config-lib)"]:::core
        end

        subgraph "I/O & Parsing"
            direction TB
            Glob["Glob Matching\n(packages/cspell-glob)"]:::core
            FileIO["File I/O Module\n(packages/cspell-io)"]:::core
            Grammar["File Parsing/Grammar\n(packages/cspell-grammar)"]:::core
        end

        subgraph "Dictionary Management"
            direction TB
            BundledDicts["Bundled Dictionaries\n(packages/cspell-bundled-dicts)"]:::core
            HunspellReader["Hunspell Reader\n(hunspell-reader)"]:::core
            TrieBuilder["Trie Builder & DS\n(packages/cspell-trie-lib)"]:::core
            LightweightTrie["Lightweight Trie Tool\n(packages/cspell-trie)"]:::core
        end

        subgraph "Suggestion Engine"
            direction TB
            CoreLib["Core Library\n(packages/cspell-lib)"]:::core
            Dictionary["Spelling Dictionary\n(packages/cspell-dictionary)"]:::core
        end

        subgraph "Integration & Reporting"
            direction TB
            CLIReporter["CLI Reporter\n(src/cli-reporter.ts)"]:::reporter
            JSONReporter["JSON Reporter\n(packages/cspell-json-reporter)"]:::reporter
            ESLintPlugin["ESLint Plugin\n(packages/cspell-eslint-plugin)"]:::reporter
        end

        subgraph "Tools & Build"
            direction TB
            DictCompiler["Dictionary Compiler\n(packages/cspell-tools)"]:::tools
            Scripts["Build Scripts\n(scripts/)"]:::tools
        end

        subgraph "Docs & Website"
            direction TB
            Website["Community Website\n(website)"]:::tools
        end

        subgraph "CI/CD & Tests"
            direction TB
            CI["GitHub Actions\n(.github/workflows)"]:::ci
            IntegrationTests["Integration Tests\n(integration-tests)"]:::ci
        end

        CLI["CLI Application\n(packages/cspell)"]:::core

        %% Flow
        CLI -->|"load config JSON"| ConfigLoader
        ConfigLoader -->|"file patterns"| Glob
        Glob -->|"file paths"| FileIO
        FileIO -->|"file streams"| Grammar
        Grammar -->|"parsed tokens"| CoreLib
        CoreLib -->|"load dictionaries"| BundledDicts
        CoreLib -->|"load dictionaries"| HunspellReader
        BundledDicts -->|"word lists"| TrieBuilder
        HunspellReader -->|"word lists"| TrieBuilder
        TrieBuilder -->|"trie data"| CoreLib
        LightweightTrie -->|"optimized trie"| DictCompiler
        CoreLib -->|"check words"| Dictionary
        Dictionary -->|"spelling issues"| CLIReporter
        Dictionary -->|"spelling issues"| JSONReporter
        CoreLib -->|"API calls"| ESLintPlugin

        CLI -->|"invoke"| IntegrationTests
        CI -->|"run lint, tests, build, deploy"| CLI
        CI -->|"run integration tests"| IntegrationTests
        CI -->|"deploy docs"| Website

    end

    %% Click Events
    click CLI "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell"
    click CoreLib "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-lib"
    click ConfigLoader "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-config-lib"
    click Glob "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-glob"
    click FileIO "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-io"
    click Grammar "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-grammar"
    click BundledDicts "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-bundled-dicts"
    click HunspellReader "https://github.com/streetsidesoftware/cspell/tree/main/hunspell-reader"
    click TrieBuilder "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-trie-lib"
    click LightweightTrie "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-trie"
    click Dictionary "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-dictionary"
    click CLIReporter "https://github.com/streetsidesoftware/cspell/blob/main/packages/cspell/src/cli-reporter.ts"
    click JSONReporter "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-json-reporter"
    click ESLintPlugin "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-eslint-plugin"
    click DictCompiler "https://github.com/streetsidesoftware/cspell/tree/main/packages/cspell-tools"
    click Website "https://github.com/streetsidesoftware/cspell/tree/main/website"
    click CI "https://github.com/streetsidesoftware/cspell/tree/main/.github/workflows"
    click IntegrationTests "https://github.com/streetsidesoftware/cspell/tree/main/integration-tests"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef reporter fill:#d4edda,stroke:#155724,color:#155724
    classDef tools fill:#fff3cd,stroke:#856404,color:#856404
    classDef ci fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
