# saltifydev/milky architecture

> Architecture diagram of the GitHub repository saltifydev/milky, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/saltifydev/milky
- Repository: https://github.com/saltifydev/milky

## Overview

Milky defines a QQ bot application API standard. Its main workflow is to assemble protocol definitions into an intermediate representation (IR), then let developers generate language types or API descriptions from that IR. The repository also provides reference documentation and raw protocol artifacts. The sampled code confirms the IR assembly, generator dispatch, and several generation paths; other generator and documentation wiring is inferred only where the tree explicitly identifies the relevant modules or routes.

Main entry points: [`common/src/index.ts`](https://github.com/saltifydev/milky/blob/main/common/src/index.ts) (Generator exports), [`protocol/src/builder.ts`](https://github.com/saltifydev/milky/blob/main/protocol/src/builder.ts) (IR builders), [`docs/app`](https://github.com/saltifydev/milky/tree/main/docs/app) (Documentation site), [`protocol/src/ir/api/index.ts`](https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/index.ts) (API categories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_protocol["Protocol definition"]
  node_protocol_entry["Protocol entry<br/>[index.ts]"]
  node_builder["IR builders<br/>[builder.ts]"]
  node_common_models["Shared entities<br/>[common.ts]"]
  node_api_index["API categories<br/>[index.ts]"]
  node_friend_apis["Friend APIs<br/>[friend.ts]"]
  node_group_apis["Group APIs<br/>[group.ts]"]
  node_message_apis["Message APIs<br/>[message.ts]"]
  node_system_apis["System APIs<br/>[system.ts]"]
end

subgraph group_generation["Spec generation"]
  node_generator_cli["Generator CLI<br/>[cli.ts]"]
  node_generator_common["Generator exports<br/>[index.ts]"]
  node_typescript_generators["TypeScript specs"]
  node_dart_generator["Dart spec"]
  node_kotlin_generator["Kotlin spec"]
  node_rust_generator["Rust spec<br/>[serde.ts]"]
  node_schema_generators["Schema specs"]
  node_openapi_generator["OpenAPI spec<br/>[index.ts]"]
  node_markdown_generator["Roadmap Markdown<br/>[roadmap.ts]"]
end

subgraph group_reference["Reference docs"]
  node_docs_app["Documentation site"]
  node_docs_content["Guides and reference"]
  node_raw_routes["Raw protocol routes"]
  node_struct_page["Struct reference<br/>[page.tsx]"]
  node_api_page["API reference<br/>[page.tsx]"]
end

node_developer(("Bot developer"))
node_bot_ecosystem(("Bot adapters"))
node_cdn(("Protocol CDN"))

node_builder -->|"builds entities"| node_common_models
node_builder -->|"builds APIs"| node_friend_apis
node_builder -->|"builds APIs"| node_group_apis
node_builder -->|"builds APIs"| node_message_apis
node_builder -->|"builds APIs"| node_system_apis
node_api_index -->|"exports category"| node_friend_apis
node_api_index -->|"exports category"| node_group_apis
node_api_index -->|"exports category"| node_message_apis
node_api_index -->|"exports category"| node_system_apis
node_protocol_entry -->|"assembles IR"| node_common_models
node_protocol_entry -->|"assembles IR"| node_api_index
node_bot_ecosystem -.->|"uses standard"| node_protocol_entry
node_developer -->|"runs"| node_generator_cli
node_generator_cli -->|"loads local IR"| node_protocol_entry
node_generator_cli -.->|"fetches versioned IR"| node_cdn
node_generator_cli -->|"dispatches generator"| node_generator_common
node_generator_common -->|"exports generators"| node_typescript_generators
node_generator_common -->|"exports generator"| node_dart_generator
node_generator_common -->|"exports generator"| node_kotlin_generator
node_generator_common -->|"exports generator"| node_rust_generator
node_generator_common -->|"exports generators"| node_schema_generators
node_generator_common -->|"exports generator"| node_openapi_generator
node_generator_common -->|"exports generator"| node_markdown_generator
node_openapi_generator -->|"loads Zod schemas"| node_schema_generators
node_developer -->|"reads reference"| node_docs_app
node_docs_app -->|"renders content"| node_docs_content
node_docs_app -->|"serves raw artifacts"| node_raw_routes
node_docs_app -->|"renders structs"| node_struct_page
node_docs_app -->|"renders API categories"| node_api_page

click node_protocol_entry "https://github.com/saltifydev/milky/blob/main/protocol/src/index.ts"
click node_builder "https://github.com/saltifydev/milky/blob/main/protocol/src/builder.ts"
click node_common_models "https://github.com/saltifydev/milky/blob/main/protocol/src/ir/common.ts"
click node_api_index "https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/index.ts"
click node_friend_apis "https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/friend.ts"
click node_group_apis "https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/group.ts"
click node_message_apis "https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/message.ts"
click node_system_apis "https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/system.ts"
click node_generator_cli "https://github.com/saltifydev/milky/blob/main/generator/src/cli.ts"
click node_generator_common "https://github.com/saltifydev/milky/blob/main/common/src/index.ts"
click node_typescript_generators "https://github.com/saltifydev/milky/tree/main/common/src/generator/typescript"
click node_dart_generator "https://github.com/saltifydev/milky/blob/main/common/src/generator/dart/json_serializable.ts"
click node_kotlin_generator "https://github.com/saltifydev/milky/blob/main/common/src/generator/kotlin/kotlinx-serialization.ts"
click node_rust_generator "https://github.com/saltifydev/milky/blob/main/common/src/generator/rust/serde.ts"
click node_schema_generators "https://github.com/saltifydev/milky/tree/main/common/src/generator"
click node_openapi_generator "https://github.com/saltifydev/milky/blob/main/common/src/generator/openapi/index.ts"
click node_markdown_generator "https://github.com/saltifydev/milky/blob/main/common/src/generator/markdown/roadmap.ts"
click node_docs_app "https://github.com/saltifydev/milky/tree/main/docs/app"
click node_docs_content "https://github.com/saltifydev/milky/tree/main/docs/content"
click node_raw_routes "https://github.com/saltifydev/milky/tree/main/docs/app/raw"
click node_struct_page "https://github.com/saltifydev/milky/blob/main/docs/app/struct/%5BcommonEntityName%5D/page.tsx"
click node_api_page "https://github.com/saltifydev/milky/blob/main/docs/app/api/%5BapiCategoryId%5D/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_protocol_entry,node_builder,node_common_models,node_api_index,node_friend_apis,node_group_apis,node_message_apis,node_system_apis toneBlue
class node_generator_cli,node_generator_common,node_typescript_generators,node_dart_generator,node_kotlin_generator,node_rust_generator,node_schema_generators,node_openapi_generator,node_markdown_generator toneAmber
class node_docs_app,node_docs_content,node_raw_routes,node_struct_page,node_api_page toneMint
class node_developer,node_bot_ecosystem,node_cdn toneIndigo
```

## Components

### Protocol definition

- [Protocol entry](https://github.com/saltifydev/milky/blob/main/protocol/src/index.ts): `protocol/src/index.ts`
- [IR builders](https://github.com/saltifydev/milky/blob/main/protocol/src/builder.ts): `protocol/src/builder.ts`
- [Shared entities](https://github.com/saltifydev/milky/blob/main/protocol/src/ir/common.ts): `protocol/src/ir/common.ts`
- [API categories](https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/index.ts): `protocol/src/ir/api/index.ts`
- [Friend APIs](https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/friend.ts): `protocol/src/ir/api/friend.ts`
- [Group APIs](https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/group.ts): `protocol/src/ir/api/group.ts`
- [Message APIs](https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/message.ts): `protocol/src/ir/api/message.ts`
- [System APIs](https://github.com/saltifydev/milky/blob/main/protocol/src/ir/api/system.ts): `protocol/src/ir/api/system.ts`

### Spec generation

- [Generator CLI](https://github.com/saltifydev/milky/blob/main/generator/src/cli.ts): `generator/src/cli.ts`
- [Generator exports](https://github.com/saltifydev/milky/blob/main/common/src/index.ts): `common/src/index.ts`
- [TypeScript specs](https://github.com/saltifydev/milky/tree/main/common/src/generator/typescript): `common/src/generator/typescript`
- [Dart spec](https://github.com/saltifydev/milky/blob/main/common/src/generator/dart/json_serializable.ts): `common/src/generator/dart/json_serializable.ts`
- [Kotlin spec](https://github.com/saltifydev/milky/blob/main/common/src/generator/kotlin/kotlinx-serialization.ts): `common/src/generator/kotlin/kotlinx-serialization.ts`
- [Rust spec](https://github.com/saltifydev/milky/blob/main/common/src/generator/rust/serde.ts): `common/src/generator/rust/serde.ts`
- [Schema specs](https://github.com/saltifydev/milky/tree/main/common/src/generator): `common/src/generator`
- [OpenAPI spec](https://github.com/saltifydev/milky/blob/main/common/src/generator/openapi/index.ts): `common/src/generator/openapi/index.ts`
- [Roadmap Markdown](https://github.com/saltifydev/milky/blob/main/common/src/generator/markdown/roadmap.ts): `common/src/generator/markdown/roadmap.ts`

### Reference docs

- [Documentation site](https://github.com/saltifydev/milky/tree/main/docs/app): `docs/app`
- [Guides and reference](https://github.com/saltifydev/milky/tree/main/docs/content): `docs/content`
- [Raw protocol routes](https://github.com/saltifydev/milky/tree/main/docs/app/raw): `docs/app/raw`
- [Struct reference](https://github.com/saltifydev/milky/blob/main/docs/app/struct/%5BcommonEntityName%5D/page.tsx): `docs/app/struct/[commonEntityName]/page.tsx`
- [API reference](https://github.com/saltifydev/milky/blob/main/docs/app/api/%5BapiCategoryId%5D/page.tsx): `docs/app/api/[apiCategoryId]/page.tsx`

### Other components

- **Bot developer**
- **Bot adapters**
- **Protocol CDN**

## Connections

- IR builders → Shared entities: builds entities
- IR builders → Friend APIs: builds APIs
- IR builders → Group APIs: builds APIs
- IR builders → Message APIs: builds APIs
- IR builders → System APIs: builds APIs
- API categories → Friend APIs: exports category
- API categories → Group APIs: exports category
- API categories → Message APIs: exports category
- API categories → System APIs: exports category
- Protocol entry → Shared entities: assembles IR
- Protocol entry → API categories: assembles IR
- Bot adapters → Protocol entry: uses standard
- Bot developer → Generator CLI: runs
- Generator CLI → Protocol entry: loads local IR
- Generator CLI → Protocol CDN: fetches versioned IR
- Generator CLI → Generator exports: dispatches generator
- Generator exports → TypeScript specs: exports generators
- Generator exports → Dart spec: exports generator
- Generator exports → Kotlin spec: exports generator
- Generator exports → Rust spec: exports generator
- Generator exports → Schema specs: exports generators
- Generator exports → OpenAPI spec: exports generator
- Generator exports → Roadmap Markdown: exports generator
- OpenAPI spec → Schema specs: loads Zod schemas
- Bot developer → Documentation site: reads reference
- Documentation site → Guides and reference: renders content
- Documentation site → Raw protocol routes: serves raw artifacts
- Documentation site → Struct reference: renders structs
- Documentation site → API reference: renders API categories