# richardsondx/checkmate architecture

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

- Interactive diagram: https://gitdiagram.com/richardsondx/checkmate
- Repository: https://github.com/richardsondx/checkmate

## Overview

##### Project type and purpose
- CheckMate is a Node.js/TypeScript CLI application and AI-powered Test-Driven-Development (TDD) framework.
- Its purpose is to generate, run, and verify “specs” (Markdown or YAML) against your code using LLMs (OpenAI & Anthropic), with optional in-editor integration via Cursor’s Middleware Control Protocol (MCP).

##### File structure
- **bin/** – Platform-agnostic CLI “wrapper” scripts (`checkmate`, `checkmateai`)
- **src/**
- commands/ – one file per CLI command (init, gen, status, watch, etc.)
- lib/ – domain libraries (AI client, file I/O, caching, telemetry, spec parsing/validation)
- mcp/ – MCP server entrypoint & router for Cursor integration
- ui/ – ASCII banner & markdown rendering utilities
- index.ts – CLI dispatcher
- **scripts/** – project-scaffolding and maintenance scripts (cursor rules, spec templates)
- **.cursor/** – Cursor AI configuration & injected rule files (.mdc)
- **dist-test/** – compiled artifacts used by “bin” (mirrors dist/) for end-to-end test harness
- **memory-docs/** & **wiki/** – design docs, guides, standards
- **tests/** – unit & integration tests
- **package.json**, **tsconfig.json**, **.checkmate-config.json** – build & runtime configuration

##### README for additional insights
- Dual-model architecture: uses “reason” (Claude) for spec generation and “quick” (GPT) for verification
- Smart caching in `.checkmate/cache/` to minimize API calls
- `.checkmate` YAML or env variables for config
- MCP server registers under `.cursor/config.json` to enable live in-editor commands
- Visual indicators in Cursor driven by injected rule files

##### Diagramming conventions
- Blue for “CLI & Commands”
- Green for “Domain Services”
- Orange for “Infrastructure (FS, Cache, Logs)”
- Purple for “External Services (OpenAI, Anthropic)”
- Gray for “Editor Integration (MCP ↔ Cursor)”
- Rectangles for modules/components
- Double-lined for in-process IPC (MCP channel)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI & Commands Layer
    subgraph "CLI & Commands"
        direction TB
        Checkmate["bin/checkmate"]:::cli
        CheckmateAI["bin/checkmateai"]:::cli
        Dispatcher["src/index.ts"]:::cli
        CommandsDir["src/commands/"]:::cli
    end

    %% Domain Services Layer
    subgraph "Core Domain Services"
        direction TB
        DomainDir["src/lib/"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure (FS, Cache, Config, Scripts, Tests)"
        direction TB
        FS["File System (.checkmate, specs)"]:::infra
        CacheDir[".checkmate/ (cache)"]:::infra
        ConfigFile[".checkmate-config.json"]:::infra
        PackageConfig["package.json & tsconfig.json"]:::infra
        ScriptsDir["scripts/"]:::infra
        TestsDir["tests/"]:::infra
        DistTest["dist-test/"]:::infra
    end

    %% MCP Integration Layer
    subgraph "Editor Integration (MCP ↔ Cursor)"
        direction TB
        MCPIndex["src/mcp/index.ts"]:::editor
        MCPRouter["src/mcp/router.ts"]:::editor
        LibMCP["src/lib/mcp.ts"]:::editor
        LibCursor["src/lib/cursor.ts"]:::editor
        CursorConfig[".cursor/config.yaml & mcp.json"]:::editor
        Rules[".cursor/rules/*.mdc"]:::editor
        CursorEditor("Cursor Editor"):::editor
    end

    %% External Services
    subgraph "External LLM APIs"
        direction TB
        OpenAI["OpenAI API"]:::external
        Anthropic["Anthropic API"]:::external
    end

    %% Documentation Assets
    subgraph "Documentation Assets"
        direction TB
        MemoryDocs["memory-docs/"]:::infra
        Wiki["wiki/"]:::infra
    end

    %% User Interaction
    User("User"):::external

    %% Connections
    User -->|"runs command"| Checkmate
    User -->|"runs command"| CheckmateAI
    Checkmate --> Dispatcher
    CheckmateAI --> Dispatcher
    Dispatcher --> CommandsDir
    CommandsDir --> DomainDir
    DomainDir --> OpenAI
    DomainDir --> Anthropic
    DomainDir --> FS
    DomainDir --> CacheDir
    DomainDir --> ConfigFile
    DomainDir --> PackageConfig
    DomainDir --> TestsDir
    DomainDir --> DistTest
    DomainDir --> ScriptsDir
    DomainDir --> MemoryDocs
    DomainDir --> Wiki

    %% MCP Integration flows
    CursorEditor <-->|"MCP Channel"| MCPIndex
    MCPIndex --> MCPRouter
    MCPRouter --> DomainDir
    MCPRouter --> LibMCP
    MCPRouter --> LibCursor
    LibMCP --> CursorConfig
    LibMCP --> Rules

    %% Click Events
    click Checkmate "https://github.com/richardsondx/checkmate/tree/main/bin/checkmate"
    click CheckmateAI "https://github.com/richardsondx/checkmate/tree/main/bin/checkmateai"
    click Dispatcher "https://github.com/richardsondx/checkmate/blob/main/src/index.ts"
    click CommandsDir "https://github.com/richardsondx/checkmate/tree/main/src/commands/"
    click DomainDir "https://github.com/richardsondx/checkmate/tree/main/src/lib/"
    click FS "https://github.com/richardsondx/checkmate/tree/main/.checkmate/"
    click CacheDir "https://github.com/richardsondx/checkmate/tree/main/.checkmate/"
    click ConfigFile "https://github.com/richardsondx/checkmate/blob/main/.checkmate-config.json"
    click PackageConfig "https://github.com/richardsondx/checkmate/blob/main/package.json"
    click ScriptsDir "https://github.com/richardsondx/checkmate/tree/main/scripts/"
    click TestsDir "https://github.com/richardsondx/checkmate/tree/main/tests/"
    click DistTest "https://github.com/richardsondx/checkmate/tree/main/dist-test/"
    click MCPIndex "https://github.com/richardsondx/checkmate/blob/main/src/mcp/index.ts"
    click MCPRouter "https://github.com/richardsondx/checkmate/blob/main/src/mcp/router.ts"
    click LibMCP "https://github.com/richardsondx/checkmate/blob/main/src/lib/mcp.ts"
    click LibCursor "https://github.com/richardsondx/checkmate/blob/main/src/lib/cursor.ts"
    click CursorConfig "https://github.com/richardsondx/checkmate/blob/main/.cursor/config.yaml"
    click Rules "https://github.com/richardsondx/checkmate/tree/main/.cursor/rules/"
    click MemoryDocs "https://github.com/richardsondx/checkmate/tree/main/memory-docs/"
    click Wiki "https://github.com/richardsondx/checkmate/tree/main/wiki/"

    %% Styles
    classDef cli fill:#BBDEFB,stroke:#1976D2,color:#000
    classDef domain fill:#C8E6C9,stroke:#388E3C,color:#000
    classDef infra fill:#FFE0B2,stroke:#F57C00,color:#000
    classDef external fill:#E1BEE7,stroke:#8E24AA,color:#000
    classDef editor fill:#CFD8DC,stroke:#455A64,color:#000
```
