# qianlin1455/go-server architecture

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

- Interactive diagram: https://gitdiagram.com/qianlin1455/go-server
- Repository: https://github.com/qianlin1455/go-server

## Overview

Go-Server is a layered Go backend for fixed-revision GitHub source imports, evidence-grounded AI questions, and project/conversation/practice-task workflows. HTTP clients enter through the API; services enforce domain rules and repositories persist state. Imports proceed asynchronously through an outbox, Kafka delivery, and a shared runner that fetches GitHub source into searchable snapshots. The README documents the major workflows; some implementation details and wiring are unsampled, so edges rely on documented relationships where source excerpts do not show calls.

Main entry points: [`cmd/server/main.go`](https://github.com/qianlin1455/go-server/blob/main/cmd/server/main.go) (API Assembly), [`internal/database/mysql.go`](https://github.com/qianlin1455/go-server/blob/main/internal/database/mysql.go) (MySQL), [`internal/service/project_service.go`](https://github.com/qianlin1455/go-server/blob/main/internal/service/project_service.go) (Project Service), [`internal/service/github_binding.go`](https://github.com/qianlin1455/go-server/blob/main/internal/service/github_binding.go) (Repository Binding)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_server["API Assembly<br/>[main.go]"]
  node_auth["Authentication<br/>[auth_service.go]"]
end

subgraph group_product["Project Workflows"]
  node_project["Project Service<br/>[project_service.go]"]
  node_conversation["Conversation Service"]
  node_message["Message Service<br/>[message_service.go]"]
  node_tasks["Practice Tasks<br/>[task_service.go]"]
  node_evidence["Task Evidence"]
  node_retrospective["Task Review"]
end

subgraph group_source["Source Intelligence"]
  node_githubbind["Repository Binding<br/>[github_binding.go]"]
  node_importapi["Import Requests<br/>[import_job.go]"]
  node_sourceapi["Snapshot Retrieval"]
  node_ask["Evidence-Grounded Ask<br/>[ask_service.go]"]
  node_llm["LLM Client<br/>[client.go]"]
end

subgraph group_imports["Async Imports"]
  node_publisher["Outbox Publisher<br/>[publisher.go]"]
  node_consumer["Kafka Consumer<br/>[handler.go]"]
  node_runner["Import Runner<br/>[runner.go]"]
end

subgraph group_infra["Persistence And Integrations"]
  node_github["GitHub Client<br/>[client.go]"]
  node_mysql[("MySQL<br/>[mysql.go]")]
  node_redis[("Redis Services<br/>[redis.go]")]
  node_kafka["Kafka"]
end

node_client(("HTTP Client"))
node_externalmodel(("Model API<br/>external service"))

node_client -->|"calls API"| node_server
node_server -->|"routes auth"| node_auth
node_server -->|"routes projects"| node_project
node_server -->|"routes conversations"| node_conversation
node_server -->|"routes messages"| node_message
node_server -->|"routes tasks"| node_tasks
node_server -->|"routes evidence"| node_evidence
node_server -->|"serves review"| node_retrospective
node_server -->|"routes binding"| node_githubbind
node_server -->|"routes imports"| node_importapi
node_server -->|"routes source"| node_sourceapi
node_server -->|"routes questions"| node_ask
node_auth -->|"stores users"| node_mysql
node_project -->|"caches details"| node_redis
node_project -->|"reads projects"| node_mysql
node_conversation -->|"persists sessions"| node_mysql
node_message -->|"stores messages"| node_mysql
node_tasks -->|"updates tasks"| node_mysql
node_evidence -->|"stores evidence"| node_mysql
node_retrospective -->|"reads audit"| node_mysql
node_githubbind -->|"resolves revision"| node_github
node_githubbind -->|"rate limits"| node_redis
node_importapi -->|"writes job outbox"| node_mysql
node_importapi -->|"gates duplicates"| node_redis
node_publisher -->|"scans outbox"| node_mysql
node_publisher -->|"publishes events"| node_kafka
node_kafka -->|"delivers events"| node_consumer
node_consumer -->|"processes jobs"| node_runner
node_consumer -->|"checks job state"| node_mysql
node_runner -->|"fetches revision"| node_github
node_runner -->|"claims and stores snapshot"| node_mysql
node_sourceapi -->|"reads snapshots"| node_mysql
node_ask -->|"retrieves evidence"| node_sourceapi
node_ask -->|"requests completion"| node_llm
node_llm -->|"calls model API"| node_externalmodel

click node_server "https://github.com/qianlin1455/go-server/blob/main/cmd/server/main.go"
click node_auth "https://github.com/qianlin1455/go-server/blob/main/internal/service/auth_service.go"
click node_project "https://github.com/qianlin1455/go-server/blob/main/internal/service/project_service.go"
click node_conversation "https://github.com/qianlin1455/go-server/blob/main/internal/service/conversation_service.go"
click node_message "https://github.com/qianlin1455/go-server/blob/main/internal/service/message_service.go"
click node_tasks "https://github.com/qianlin1455/go-server/blob/main/internal/service/task_service.go"
click node_evidence "https://github.com/qianlin1455/go-server/blob/main/internal/service/task_evidence_service.go"
click node_retrospective "https://github.com/qianlin1455/go-server/blob/main/internal/service/task_retrospective.go"
click node_githubbind "https://github.com/qianlin1455/go-server/blob/main/internal/service/github_binding.go"
click node_importapi "https://github.com/qianlin1455/go-server/blob/main/internal/service/import_job.go"
click node_sourceapi "https://github.com/qianlin1455/go-server/blob/main/internal/service/source_retrieval.go"
click node_ask "https://github.com/qianlin1455/go-server/blob/main/internal/service/ask_service.go"
click node_llm "https://github.com/qianlin1455/go-server/blob/main/internal/llmclient/client.go"
click node_publisher "https://github.com/qianlin1455/go-server/blob/main/internal/publisher/publisher.go"
click node_consumer "https://github.com/qianlin1455/go-server/blob/main/internal/consumer/handler.go"
click node_runner "https://github.com/qianlin1455/go-server/blob/main/internal/worker/runner.go"
click node_github "https://github.com/qianlin1455/go-server/blob/main/internal/githubclient/client.go"
click node_mysql "https://github.com/qianlin1455/go-server/blob/main/internal/database/mysql.go"
click node_redis "https://github.com/qianlin1455/go-server/blob/main/internal/cache/redis.go"

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_server,node_auth,node_client toneBlue
class node_project,node_conversation,node_message,node_tasks,node_evidence,node_retrospective toneAmber
class node_githubbind,node_importapi,node_sourceapi,node_ask,node_llm,node_externalmodel toneMint
class node_publisher,node_consumer,node_runner toneRose
class node_github,node_mysql,node_redis,node_kafka toneIndigo
```

## Components

### HTTP API

- [API Assembly](https://github.com/qianlin1455/go-server/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [Authentication](https://github.com/qianlin1455/go-server/blob/main/internal/service/auth_service.go): `internal/service/auth_service.go`

### Project Workflows

- [Project Service](https://github.com/qianlin1455/go-server/blob/main/internal/service/project_service.go): `internal/service/project_service.go`
- [Conversation Service](https://github.com/qianlin1455/go-server/blob/main/internal/service/conversation_service.go): `internal/service/conversation_service.go`
- [Message Service](https://github.com/qianlin1455/go-server/blob/main/internal/service/message_service.go): `internal/service/message_service.go`
- [Practice Tasks](https://github.com/qianlin1455/go-server/blob/main/internal/service/task_service.go): `internal/service/task_service.go`
- [Task Evidence](https://github.com/qianlin1455/go-server/blob/main/internal/service/task_evidence_service.go): `internal/service/task_evidence_service.go`
- [Task Review](https://github.com/qianlin1455/go-server/blob/main/internal/service/task_retrospective.go): `internal/service/task_retrospective.go`

### Source Intelligence

- [Repository Binding](https://github.com/qianlin1455/go-server/blob/main/internal/service/github_binding.go): `internal/service/github_binding.go`
- [Import Requests](https://github.com/qianlin1455/go-server/blob/main/internal/service/import_job.go): `internal/service/import_job.go`
- [Snapshot Retrieval](https://github.com/qianlin1455/go-server/blob/main/internal/service/source_retrieval.go): `internal/service/source_retrieval.go`
- [Evidence-Grounded Ask](https://github.com/qianlin1455/go-server/blob/main/internal/service/ask_service.go): `internal/service/ask_service.go`
- [LLM Client](https://github.com/qianlin1455/go-server/blob/main/internal/llmclient/client.go): `internal/llmclient/client.go`

### Async Imports

- [Outbox Publisher](https://github.com/qianlin1455/go-server/blob/main/internal/publisher/publisher.go): `internal/publisher/publisher.go`
- [Kafka Consumer](https://github.com/qianlin1455/go-server/blob/main/internal/consumer/handler.go): `internal/consumer/handler.go`
- [Import Runner](https://github.com/qianlin1455/go-server/blob/main/internal/worker/runner.go): `internal/worker/runner.go`

### Persistence And Integrations

- [GitHub Client](https://github.com/qianlin1455/go-server/blob/main/internal/githubclient/client.go): `internal/githubclient/client.go`
- [MySQL](https://github.com/qianlin1455/go-server/blob/main/internal/database/mysql.go): `internal/database/mysql.go`
- [Redis Services](https://github.com/qianlin1455/go-server/blob/main/internal/cache/redis.go): `internal/cache/redis.go`
- **Kafka**

### Other components

- **HTTP Client**
- **Model API**: external service

## Connections

- HTTP Client → API Assembly: calls API (evidence: `README.md`)
- API Assembly → Authentication: routes auth (evidence: `cmd/server/main.go`)
- API Assembly → Project Service: routes projects (evidence: `README.md`)
- API Assembly → Conversation Service: routes conversations (evidence: `README.md`)
- API Assembly → Message Service: routes messages (evidence: `README.md`)
- API Assembly → Practice Tasks: routes tasks (evidence: `README.md`)
- API Assembly → Task Evidence: routes evidence (evidence: `README.md`)
- API Assembly → Task Review: serves review (evidence: `README.md`)
- API Assembly → Repository Binding: routes binding (evidence: `README.md`)
- API Assembly → Import Requests: routes imports (evidence: `README.md`)
- API Assembly → Snapshot Retrieval: routes source (evidence: `README.md`)
- API Assembly → Evidence-Grounded Ask: routes questions (evidence: `README.md`)
- Authentication → MySQL: stores users (evidence: `internal/service/auth_service.go`)
- Project Service → Redis Services: caches details (evidence: `README.md`)
- Project Service → MySQL: reads projects (evidence: `README.md`)
- Conversation Service → MySQL: persists sessions (evidence: `README.md`)
- Message Service → MySQL: stores messages (evidence: `README.md`)
- Practice Tasks → MySQL: updates tasks (evidence: `README.md`)
- Task Evidence → MySQL: stores evidence (evidence: `README.md`)
- Task Review → MySQL: reads audit (evidence: `README.md`)
- Repository Binding → GitHub Client: resolves revision (evidence: `README.md`)
- Repository Binding → Redis Services: rate limits (evidence: `README.md`)
- Import Requests → MySQL: writes job outbox (evidence: `README.md`)
- Import Requests → Redis Services: gates duplicates (evidence: `README.md`)
- Outbox Publisher → MySQL: scans outbox (evidence: `README.md`)
- Outbox Publisher → Kafka: publishes events (evidence: `README.md`)
- Kafka → Kafka Consumer: delivers events (evidence: `README.md`)
- Kafka Consumer → Import Runner: processes jobs (evidence: `internal/consumer/handler.go`)
- Kafka Consumer → MySQL: checks job state (evidence: `internal/consumer/handler.go`)
- Import Runner → GitHub Client: fetches revision (evidence: `README.md`)
- Import Runner → MySQL: claims and stores snapshot (evidence: `README.md`)
- Snapshot Retrieval → MySQL: reads snapshots (evidence: `README.md`)
- Evidence-Grounded Ask → Snapshot Retrieval: retrieves evidence (evidence: `README.md`)
- Evidence-Grounded Ask → LLM Client: requests completion (evidence: `README.md`)
- LLM Client → Model API: calls model API (evidence: `README.md`)
