# miyamo2/qilin architecture

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

- Interactive diagram: https://gitdiagram.com/miyamo2/qilin
- Repository: https://github.com/miyamo2/qilin

## Overview

##### Project type and purpose
- Qilin is a Go-based framework (library) for building Model Context Protocol (MCP) servers that communicate over STDIN/STDOUT.
- It provides a zero-config “server” that lets you register “tools” and “resources” with handlers, bind JSON payloads, and emit JSON responses.

##### File structure
Top-level files and directories:
- core sources: `qilin.go`, `context.go`, `errors.go`, `types.go`
- transport layer: `transport/transport.go`, `transport/stdio.go`
- examples: full sample app under `examples/weather/...` showing domain, repository, handler, infrastructure/API, main.go
- tests, helpers, configs, module files

##### README for additional insights
- Provides the high-level API: `qilin.New()`, `Tool()`, `Start()`
- Highlights supported “transports” (only STDIO) and features (Tool, Resource)
- Demonstrates typical handler signature and JSON binding

##### Main components

A. Qilin Core Framework
- Package entrypoint: `qilin.New()` → `Starter`
- Handler registration (`Tool()`, `Resource()`)
- Dispatcher / router that maps incoming JSON requests to the correct handler

B. Transport Layer
- STDIO transport implementation (`transport/stdio.go`)
- Reads raw bytes from STDIN → parses into request objects
- Serializes responses into raw bytes → writes to STDOUT

C. Handler Context
- `ToolContext` abstraction: Bind, JSON, error handling
- Middleware pipeline support

D. User Application (Examples)
- Domain models and repos (`examples/weather/domain/...`)
- Business logic in handler functions (`examples/weather/handler/handler.go`)
- Infrastructure adapters/API clients (`examples/weather/infrastructure/api/...`)
- `main.go` wiring it all together

E. External Client
- Any process or client that writes JSON MCP messages to STDIN and reads JSON from STDOUT

##### Relationships & Data Flow
1. External Client → STDIN
2. STDIO Transport reads bytes → unmarshals into a Qilin Request
3. Core Dispatcher identifies the matching Handler
4. HandlerContext.Bind() parses params → Business Logic (domain + infra)
5. HandlerContext.JSON() serializes response → Core
6. STDIO Transport writes JSON bytes → STDOUT → External Client

##### Architectural patterns & design principles
- Inversion of Control: user registers handlers; Qilin calls them
- Layered architecture: Transport → Core → Handler → Domain → Infrastructure
- Zero-config convention over configuration

##### Technologies & frameworks
- Go modules, standard library JSON, interfaces for Transport & Context
- Example shows domain-driven structure (model/repository)
- Tests under `*_test.go` demonstrating usage

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Client
    EC["External Client"]:::external

    %% Transport Layer
    subgraph "Transport Layer"
        TI["Transport Interface"]:::transport
        STDIO["STDIO Transport"]:::transport
    end

    %% Qilin Core Framework
    subgraph "Qilin Core Framework"
        API["API Surface (qilin.New(), Tool(), Start())"]:::core
        DSP["Dispatcher (types.go)"]:::core
        CTX["HandlerContext & Middleware (context.go)"]:::core
        ERR["Error Handling (errors.go)"]:::core
    end

    %% User Application (Example Weather App)
    subgraph "User Application"
        MAIN["App Entry (main.go)"]:::app
        HND["Handler Definitions"]:::app
        DOM["Domain Model"]:::domain
        REP["Repository"]:::domain
        INF["Infra API Client"]:::infra
    end

    %% Data Flow
    EC -->|"Writes JSON MCP Request"| STDIO
    STDIO -->|"Unmarshal JSON"| DSP
    DSP -->|"Match & Invoke Handler"| CTX
    CTX -->|"Bind Params & Call"| HND
    HND -->|"Use Domain & Repo"| DOM
    HND -->|"Use Infra Client"| INF
    HND -->|"Return Data"| CTX
    CTX -->|"Marshal JSON"| STDIO
    STDIO -->|"Writes JSON MCP Response"| EC

    %% Registration Flow
    MAIN -->|"Register Handlers"| API
    API -->|"Setup Dispatcher & Context"| DSP

    %% Click Events
    click TI "https://github.com/miyamo2/qilin/blob/main/transport/transport.go"
    click STDIO "https://github.com/miyamo2/qilin/blob/main/transport/stdio.go"
    click API "https://github.com/miyamo2/qilin/blob/main/qilin.go"
    click DSP "https://github.com/miyamo2/qilin/blob/main/types.go"
    click CTX "https://github.com/miyamo2/qilin/blob/main/context.go"
    click ERR "https://github.com/miyamo2/qilin/blob/main/errors.go"
    click HND "https://github.com/miyamo2/qilin/blob/main/examples/weather/handler/handler.go"
    click DOM "https://github.com/miyamo2/qilin/blob/main/examples/weather/domain/model/weather.go"
    click REP "https://github.com/miyamo2/qilin/blob/main/examples/weather/domain/repository/wather.go"
    click INF "https://github.com/miyamo2/qilin/blob/main/examples/weather/infrastructure/api/weather.go"
    click MAIN "https://github.com/miyamo2/qilin/blob/main/examples/weather/main.go"

    %% Styles
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px
    classDef transport fill:#a2d5c6,stroke:#333,stroke-width:1px
    classDef core fill:#79aec8,stroke:#333,stroke-width:1px
    classDef app fill:#f4a261,stroke:#333,stroke-width:1px
    classDef domain fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#333,stroke-width:1px
```
