# vadiml1024/semcheck architecture

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

- Interactive diagram: https://gitdiagram.com/vadiml1024/semcheck
- Repository: https://github.com/vadiml1024/semcheck

## Overview

##### Project type and purpose
- Semcheck is a command‐line and server‐based tool in Go.
- Purpose: Validate that code matches specifications by running semantic rules through LLM providers.
- Modes of operation:
– CLI mode (`cmd/cli`) for local execution and pre‐commit hooks
– Evaluation mode (`cmd/eval`) for running test cases and benchmarks
– MCP Server mode (`internal/mcp`, `main.go -mcp-server`) for TCP‐based integration.

##### File structure
- Top‐level “cmd” directory contains the entrypoints:
– `cmd/cli` → CLI commands (`init`, default check)
– `cmd/eval` → test harness for evaluation cases.
- `main.go` ties together config parsing and mode selection.
- `internal/` houses core packages:
– `config`: loads and validates `semcheck.yaml`
– `checker`: orchestrates rules, invokes prompts, collects LLM responses, reporters
– `processor`: matches files to rules, reads specs and implementations
– `providers`: pluggable LLM client interfaces (OpenAI, Anthropic, Gemini, Cerebras, Ollama)
– `mcp`: TCP server implementation of Model Context Protocol
- Other directories:
– `docs/`, `specs/`: human‐readable specifications and protocol docs
– `evals/` and `examples/`: sample inputs, test cases, and example configs.

##### Extract architectural clues from the README
- Key components mentioned: CLI, “Bring Your Own Model” providers, MCP server, remote specs.
- Workflow: config → rule dispatch → LLM provider → reporter (stdout, GitHub).
- Technologies: Go modules, Just, GitHub Actions integration.

##### Main components & their interactions

A. Frontend / Entry Points
1. CLI Component (cmd/cli)
– Reads user flags, invokes init or check commands
2. Eval Component (cmd/eval)
– Runs predefined evaluation cases for development

B. Core Engine
3. Config Loader (`internal/config`)
– Parses `semcheck.yaml` or passed flags
4. Processor (`internal/processor`)
– Scans filesystem, matches files to rules
– Reads spec and implementation content
5. Checker (`internal/checker`)
– Builds prompt templates, calls LLM client
– Aggregates LLM responses, applies pass/fail logic
6. Reporter (`internal/checker/*.go`)
– Outputs results to stdout or GitHub via reporter interfaces

C. External Integrations
7. Providers (`internal/providers`)
– Abstract client interface
– Implementations for OpenAI, Anthropic, Gemini, Cerebras, Ollama
8. Remote Spec Fetcher (HTTP)
– Fetches spec text from URLs
9. MCP Server (`internal/mcp`)
– Listens on TCP port, translates MCP requests to Checker calls

D. Supporting Elements
10. Examples & Docs (`examples`, `docs`, `specs`)
– Input templates, documentation
11. Test Suites (`internal/*_test.go`, `evals/cases`)
– Validation of each component’s behavior

E. External Services
12. LLM APIs (OpenAI, Anthropic, etc.)
13. GitHub (for GitHub Actions and GitHub Reporter)

- Config Loader → Processor → Checker
- Checker ↔ Providers (LLM request/response)
- Checker → Reporter → Stdout or GitHub API
- CLI with `-mcp-server` option starts MCP Server, which → Checker
- Processor may fetch spec files via HTTP → Remote Spec Server
- GitHub Actions workflow (external) → invokes CLI container

##### Architectural patterns & design principles
- Separation of Concerns: distinct packages for config, processing, checking, reporting
- Plugin pattern for LLM providers (common `client.go` interface)
- Hexagonal architecture for core engine → adapters (providers, reporters, MCP)
- Test‐driven development: extensive `*_test.go` files in each package
- Self‐hosted introspection: Semcheck checks its own specs (`specs/semcheck.md`)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        CLI["CLI Component"]:::frontend
        Eval["Eval Component"]:::frontend
        Main["Main Entrypoint & Mode Selection"]:::frontend
    end

    %% Core Engine
    subgraph "Core Engine"
        Config["Config Loader"]:::core
        Processor["Processor"]:::core
        Checker["Checker Engine"]:::core
        Reporter["Reporter"]:::core
    end

    %% Adapters & Integrations
    subgraph "Adapters & Integrations"
        Providers["LLM Providers"]:::adapter
        MCP["MCP Server"]:::adapter
        RemoteSpec["Remote Spec Fetcher"]:::adapter
    end

    %% Supporting & External
    subgraph "Supporting Elements"
        Docs["Documentation & Specs"]:::external
        Evals["Evaluation Test Cases"]:::external
        Tests["Package Test Suites"]:::external
    end

    subgraph "External Services"
        LLMAPIs["LLM APIs"]:::external
        GitHub["GitHub API"]:::external
    end

    %% Connections
    CLI -->|uses| Main
    Eval -->|uses| Main
    Main -->|loads config| Config
    Config -->|matches files| Processor
    Processor -->|invokes| Checker
    Processor -.->|HTTP GET| RemoteSpec
    Checker -->|aggregates & dispatches| Reporter
    Checker -->|calls| Providers
    Providers -->|responses| Checker
    Reporter -->|stdout output| CLI
    Reporter -->|GitHub Actions| GitHub
    Main -->| -mcp-server| MCP
    MCP -->|gRPC/TCP| Checker
    LLMAPIs -->|LLM API call| Providers

    %% Click Events
    click CLI "https://github.com/vadiml1024/semcheck/blob/main/cmd/cli/cli.go"
    click CLI "https://github.com/vadiml1024/semcheck/blob/main/cmd/cli/init.go"
    click Eval "https://github.com/vadiml1024/semcheck/blob/main/cmd/eval/eval.go"
    click Eval "https://github.com/vadiml1024/semcheck/blob/main/cmd/eval/main.go"
    click Main "https://github.com/vadiml1024/semcheck/blob/main/main.go"
    click Config "https://github.com/vadiml1024/semcheck/blob/main/internal/config/config.go"
    click Processor "https://github.com/vadiml1024/semcheck/blob/main/internal/processor/matcher.go"
    click Processor "https://github.com/vadiml1024/semcheck/blob/main/internal/processor/git.go"
    click Checker "https://github.com/vadiml1024/semcheck/blob/main/internal/checker/semantic.go"
    click Checker "https://github.com/vadiml1024/semcheck/blob/main/internal/checker/prompt_template.go"
    click Reporter "https://github.com/vadiml1024/semcheck/blob/main/internal/checker/reporter.go"
    click Reporter "https://github.com/vadiml1024/semcheck/blob/main/internal/checker/stdout_reporter.go"
    click Reporter "https://github.com/vadiml1024/semcheck/blob/main/internal/checker/github_reporter.go"
    click Providers "https://github.com/vadiml1024/semcheck/blob/main/internal/providers/client.go"
    click Providers "https://github.com/vadiml1024/semcheck/blob/main/internal/providers/openai.go"
    click Providers "https://github.com/vadiml1024/semcheck/blob/main/internal/providers/anthropic.go"
    click Providers "https://github.com/vadiml1024/semcheck/blob/main/internal/providers/gemini.go"
    click Providers "https://github.com/vadiml1024/semcheck/blob/main/internal/providers/cerebras.go"
    click Providers "https://github.com/vadiml1024/semcheck/blob/main/internal/providers/ollama.go"
    click MCP "https://github.com/vadiml1024/semcheck/blob/main/internal/mcp/server.go"
    click Docs "https://github.com/vadiml1024/semcheck/blob/main/docs/MCP.md"
    click Docs "https://github.com/vadiml1024/semcheck/blob/main/specs/semcheck.md"
    click Docs "https://github.com/vadiml1024/semcheck/blob/main/specs/example.md"
    click Docs "https://github.com/vadiml1024/semcheck/tree/main/examples/"
    click Evals "https://github.com/vadiml1024/semcheck/tree/main/evals/cases/"
    click Tests "https://github.com/vadiml1024/semcheck/blob/main/internal/config/config_test.go"
    click Tests "https://github.com/vadiml1024/semcheck/blob/main/internal/processor/matcher_test.go"
    click Tests "https://github.com/vadiml1024/semcheck/blob/main/internal/checker/semantic_test.go"
    click Tests "https://github.com/vadiml1024/semcheck/blob/main/internal/providers/client_test.go"
    click Tests "https://github.com/vadiml1024/semcheck/blob/main/internal/mcp/server_test.go"
    click Tests "https://github.com/vadiml1024/semcheck/blob/main/internal/mcp/integration_test.go"
    click Tests "https://github.com/vadiml1024/semcheck/blob/main/internal/mcp/tools_test.go"
    click Tests "https://github.com/vadiml1024/semcheck/blob/main/cmd/cli/init_test.go"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#98FB98,stroke:#333,stroke-width:1px
    classDef adapter fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
