# g-pegasus/zhiguang_be architecture

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

- Interactive diagram: https://gitdiagram.com/g-pegasus/zhiguang_be
- Repository: https://github.com/g-pegasus/zhiguang_be

## Overview

这是一个以 Spring Boot 为核心的后端“模块化单体”仓库，面向知识社区“知光平台”。整体不是按微服务独立仓库拆分，而是按业务域在同一应用中分包组织，并通过 MySQL、Redis、Kafka、Elasticsearch、OSS、Canal 等基础设施实现异步化、缓存化和搜索/AI 能力。

#### 1. 总体架构形态

入口应用是 `com.tongji.ZhiGuangApplication`，所有业务模块都挂在同一个 Java 进程里运行。代码结构体现出清晰的分层：

- `api`：HTTP 接口层，负责接收请求和返回 DTO
- `service` / `service.impl`：业务编排层
- `mapper`：MyBatis 持久化访问层
- `model` / `domain` / `entity`：领域对象与数据行映射
- `config`：模块级或全局配置
- `event` / `outbox` / `listener` / `processor`：异步事件与最终一致性相关组件
- `token` / `verification` / `audit`：认证、验证码、审计子域

仓库里同时存在：
- `db/schema.sql`：数据库结构定义
- `src/main/resources/mapper/*.xml`：MyBatis SQL 映射
- `src/main/resources/keys/*.pem`：JWT 非对称签名密钥
- `docs/`：多个子系统的设计和接口文档

这说明后端是“以业务域为中心、以基础设施能力支撑”的架构，而不是简单 CRUD 项目。

#### 2. 主要业务子系统

##### 2.1 认证与安全子系统 `auth`
核心文件：
- `auth/api/AuthController`
- `auth/service/AuthService`
- `auth/token/JwtService`
- `auth/token/RedisRefreshTokenStore`
- `auth/verification/VerificationService`
- `auth/audit/LoginLogService`
- `auth/config/SecurityConfig`

职责：
- 登录、注册、登出、刷新令牌、密码重置
- 验证码发送与校验
- 登录审计记录
- JWT 双令牌体系：访问令牌 + 刷新令牌
- 使用 RS256 与 `private.pem` / `public.pem` 做非对称签名
- 刷新令牌白名单保存在 Redis，用于即时撤销

数据流大致是：
1. 客户端提交登录/注册请求到 `AuthController`
2. `AuthService` 校验身份信息、验证码等
3. 生成 JWT token pair
4. 刷新令牌写入 Redis
5. 登录行为写入 `LoginLog` 对应的 MyBatis 表
6. 认证由 Spring Security 统一拦截

这个子系统是全站权限边界的入口，其他模块的接口通常会依赖认证上下文。

##### 2.2 用户资料子系统 `profile` 与用户基础域 `user`
核心文件：
- `profile/api/ProfileController`
- `profile/service/ProfileService`
- `user/domain/User`
- `user/service/UserService`
- `user/mapper/UserMapper`

职责：
- 用户基础资料与展示资料管理
- 用户信息的读取和局部修改
- 与认证身份和关系系统共享用户主数据

这里可以看出用户主数据与展示资料是分开的：`user` 更偏基础账户实体，`profile` 更偏业务展示与可修改字段。它们共同构成用户中心能力。

##### 2.3 知识内容发布子系统 `knowpost`
核心文件：
- `knowpost/api/KnowPostController`
- `knowpost/api/KnowPostAiController`
- `knowpost/api/KnowPostRagController`
- `knowpost/service/KnowPostService`
- `knowpost/service/KnowPostFeedService`
- `knowpost/mapper/KnowPostMapper`
- `knowpost/listener/FeedCacheInvalidationListener`
- `knowpost/id/SnowflakeIdGenerator`

职责：
- 知识内容草稿、发布、编辑、置顶、可见性修改
- Feed 相关内容聚合和分页展示
- AI 辅助生成摘要/描述
- 与缓存、搜索、计数、关系系统联动

这里的一个关键特征是“发布链路”不只是写数据库：
- 内容主记录落库到 MySQL
- 发布后触发缓存失效
- 可能同步或异步推动搜索索引更新
- AI 能力通过 `llm` 模块参与摘要生成
- 生成内容 ID 使用雪花算法，便于分布式唯一性和时间排序

##### 2.4 计数与互动子系统 `counter`
核心文件：
- `counter/api/CounterController`
- `counter/api/ActionController`
- `counter/service/CounterService`
- `counter/service/UserCounterService`
- `counter/event/*`
- `counter/schema/*`

职责：
- 笔记维度计数：点赞、收藏等
- 用户维度计数：关注、取关等
- 高并发下的幂等写入、异步聚合、重建修复
- Redis 作为主要计数存储，配合位图/分片 schema
- Kafka 驱动事件流转与异步消费

这是一个非常独立的子系统，和传统“数据库直接加减计数”不同，它更偏事件驱动与缓存友好：
- 写入通过事件生产者进入 Kafka
- 聚合消费者消费后更新 Redis 中的计数结构
- 重建消费者用于数据恢复或修正
- `schema` 包中定义了计数键、位图分片和键命名规则
- 该模块的设计目标是高并发、幂等和可重建

如果要画架构图，这一块应单独标出“写入事件流 → Kafka → 聚合处理 → Redis 计数存储 → 查询接口”的链路。

##### 2.5 用户关系子系统 `relation`
核心文件：
- `relation/api/RelationController`
- `relation/service/RelationService`
- `relation/processor/RelationEventProcessor`
- `relation/outbox/*`
- `relation/mapper/RelationMapper`
- `relation/event/RelationEvent`

职责：
- 关注 / 取关关系管理
- 粉丝、关注列表的同步与查询
- 通过 Outbox 模式保证主数据和事件的一致性
- 通过 Canal 监听数据库变更，再转发到 Kafka

这是仓库里最典型的“事务内写主表 + Outbox 表”的最终一致性设计：
1. 关注操作在本地事务内同时写入关系表和 outbox 表
2. Canal 订阅 outbox 表 binlog
3. `CanalKafkaBridge` / `CanalOutboxConsumer` 将变更转成 Kafka 事件
4. `RelationEventProcessor` 消费事件，异步更新从数据源
5. 从数据源可能包括计数系统、缓存、列表视图等

README 里提到“粉丝表、计数系统、列表缓存都作为关注表的伪从”，这说明关系主表是权威来源，其他视图都是派生副本。

##### 2.6 搜索子系统 `search`
核心文件：
- `search/api/SearchController`
- `search/service/SearchService`
- `search/index/SearchIndexService`
- `search/index/SearchIndexInitializer`
- `search/outbox/CanalOutboxConsumerSearch`

职责：
- 内容搜索
- 前缀联想
- 搜索索引初始化
- 从数据库变更事件同步到 Elasticsearch

这里的关键边界是：搜索不是直接查业务库，而是查 ES 索引。索引更新依赖 outbox/canal 事件管道，保证内容发布/修改后搜索侧最终一致。

README 提到的能力包括：
- 关键词检索
- 标签过滤
- `search_after` 深分页
- `function_score` 混合 BM25 与业务权重
- completion suggester 联想

因此这块应画成“业务库 → 变更事件 → 索引服务 → Elasticsearch → 查询 API”的独立搜索链路。

##### 2.7 存储子系统 `storage`
核心文件：
- `storage/OssStorageService`
- `storage/api/StorageController`
- `storage/config/OssProperties`

职责：
- OSS 对象存储直传的预签名能力
- 文件/图片/视频等资源上传前的签名授权
- 减少后端中转流量

数据流：
1. 客户端向 `StorageController` 请求预签名
2. 后端生成 OSS 直传所需签名参数
3. 客户端直接上传到阿里云 OSS
4. 内容发布时只保存资源地址/元数据

这意味着媒体流量不经过应用服务器，是发布系统的重要边界。

##### 2.8 AI / RAG 子系统 `llm`
核心文件：
- `llm/LlmConfig`
- `llm/service/KnowPostDescriptionService`
- `llm/service/impl/KnowPostDescriptionServiceImpl`
- `llm/rag/RagIndexService`
- `llm/rag/RagQueryService`

职责：
- 文章描述/摘要生成
- 基于知识库的问答
- RAG 索引构建和检索

README 说明了典型流程：
- 用户发起问答
- 检查索引
- 向量/语义检索
- Prompt 构造
- 大模型流式生成

这表明 `llm` 模块不是泛化的大模型网关，而是围绕“单篇知文/知识内容”的场景做的专用增强能力。它和 `knowpost` 绑定最紧密。

#### 3. 基础设施与跨切关注点

##### 3.1 全局配置与平台支撑
核心文件：
- `config/RedissonConfig`
- `config/ThreadPoolConfig`
- `config/ElasticsearchConfig`
- `config/EsProperties`

这些配置类说明系统对 Redis、ES、线程池做了统一管理。Redis 既用于刷新令牌、验证码、计数，也用于缓存和热点防护；ES 用于搜索；线程池用于异步任务和事件处理。

##### 3.2 缓存体系 `cache`
核心文件：
- `cache/config/CacheConfig`
- `cache/hotkey/HotKeyDetector`

职责：
- 热点识别
- 缓存策略配置

README 中提到 Feed 使用三级缓存：
- 本地 Caffeine
- Redis 页面缓存
- Redis 片段缓存

再加上热点探测和随机抖动，说明缓存层是全局性能边界的一部分，不只是单个模块内部优化。

##### 3.3 通用异常与工具
核心文件：
- `common/exception/BusinessException`
- `common/exception/ErrorCode`
- `common/web/GlobalExceptionHandler`
- `common/util/OutboxMessageUtil`

这是一层跨模块公共能力：
- 统一业务异常模型
- 统一 API 错误映射
- outbox 消息封装工具

它让各业务模块的错误处理和事件构造保持一致。

#### 4. 关键数据流和边界

如果从架构图角度看，这个仓库最重要的几条主链路是：

##### A. 身份认证链路
客户端 → Auth API → Spring Security / JWT → Redis 刷新令牌 → 受保护业务接口

边界：认证是全局入口，决定其他模块是否可访问。

##### B. 内容发布链路
客户端 → KnowPost API → MySQL 主库 → 缓存失效 / 搜索索引更新 / AI 摘要 / 计数与关系联动

边界：内容主数据在 MySQL，其他系统是派生视图或增强能力。

##### C. 关注关系链路
客户端 → Relation API → 事务写关系表 + Outbox → Canal → Kafka → 关系从表/缓存/计数系统

边界：主写入在关系表，异步消费者负责副本同步。

##### D. 互动计数链路
客户端行为 → Counter API → Kafka 事件 → Redis 位图/分片计数 → 查询接口返回聚合结果

边界：Redis 是高并发计数工作区，不是唯一事实源，允许重建。

##### E. 搜索链路
内容变更 → Outbox/Canal → Search index service → Elasticsearch → Search API

边界：ES 是读模型，来源于业务库事件流。

##### F. AI 问答链路
用户提问 → RAG 查询服务 → 索引检索 → Prompt 构造 → LLM 输出

边界：LLM 模块只消费内容索引与知识片段，不直接成为业务事实源。

#### 5. 外部依赖与它们的角色

这些外部系统对架构有直接影响：

- MySQL：主业务数据存储，尤其是用户、关系、内容、审计、outbox 等
- Redis：验证码、刷新令牌、计数、缓存、热点控制
- Kafka：异步事件总线，承载计数、关系、搜索等最终一致性流程
- Canal：监听 MySQL binlog，将 outbox 或变更事件送入 Kafka
- Elasticsearch：内容搜索与联想建议
- 阿里云 OSS：媒体/附件对象存储直传
- Spring Security / JWT：统一认证授权
- Spring AI / LLM：摘要和问答能力

#### 6. 架构图上建议如何分区

如果要画成一张准确的系统架构图，建议按以下边界分区：

1. **接入层**
   - 各 Controller
   - 统一异常处理
   - Security 拦截链

2. **业务域层**
   - auth
   - user / profile
   - knowpost
   - relation
   - counter
   - search
   - storage
   - llm

3. **异步与一致性层**
   - outbox
   - canal bridge/consumer
   - Kafka consumers/producers
   - counter aggregation / rebuild
   - feed cache invalidation

4. **基础设施层**
   - MySQL
   - Redis / Redisson
   - Kafka
   - Elasticsearch
   - OSS
   - LLM/AI 服务

5. **横切能力**
   - 缓存配置
   - 线程池
   - 全局异常
   - 通用错误码
   - 日志审计

#### 7. 总结

这个仓库的本质是一个“知识社区后端平台”的模块化单体架构，核心特征不是接口数量，而是多个子系统围绕同一份业务主数据构建出了不同的读写模型：

- MySQL 负责权威写入
- Redis 负责认证、缓存、计数和高频读
- Kafka/Canal 负责异步一致性
- Elasticsearch 负责搜索读模型
- OSS 负责静态资源
- LLM/RAG 负责内容智能化增强

从系统设计上看，最重要的架构关键词是：
“分域、事件驱动、读写分离、最终一致性、缓存多级化、搜索索引化、AI 增强化”。

Main entry points: [`src/main/java/com/tongji/ZhiGuangApplication.java`](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/ZhiGuangApplication.java) (ZhiGuang), [`src/main/java/com/tongji/knowpost/api/KnowPostController.java`](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/knowpost/api/KnowPostController.java) (KnowPost), [`src/main/java/com/tongji/auth/service/AuthService.java`](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/auth/service/AuthService.java) (Auth service), [`src/main/java/com/tongji/counter/event/CounterEventProducer.java`](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/counter/event/CounterEventProducer.java) (Kafka)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph "Application"
  n_app(("ZhiGuang<br/>spring-boot app"))
  n_global_exc["Errors<br/>web advice"]
  n_common["Common util<br/>shared helpers"]
end

subgraph "Business domains"
  n_auth_api["Auth API<br/>security api"]
  n_auth_core["Auth service<br/>security core<br/>[AuthService.java]"]
  n_auth_token["JWT store<br/>token service<br/>[JwtService.java]"]
  n_auth_verif["Verification<br/>code service"]
  n_profile["Profile"]
  n_user["User model<br/>account domain<br/>[User.java]"]
  n_knowpost["KnowPost<br/>content domain"]
  n_knowpost_ai["Post AI<br/>content ai"]
  n_counter["Counter<br/>interaction domain"]
  n_relation["Relation<br/>graph domain"]
  n_search["Search<br/>read model"]
  n_storage["Storage"]
  n_llm["LLM/RAG<br/>ai service<br/>[LlmConfig.java]"]
end

subgraph "Infrastructure"
  n_redisson[("Redis<br/>cache client")]
  n_kafka["Kafka<br/>event bus"]
  n_es[("Elasticsearch<br/>search engine")]
  n_oss[("OSS<br/>object store<br/>[OssProperties.java]")]
  n_mysql[("MySQL<br/>primary db<br/>[schema.sql]")]
  n_canal["Canal<br/>binlog bridge"]
end

n_app -->|"handles errors"| n_global_exc
n_app -->|"exposes"| n_auth_api
n_app -->|"exposes"| n_profile
n_app -->|"exposes"| n_knowpost
n_app -->|"exposes"| n_counter
n_app -->|"exposes"| n_relation
n_app -->|"exposes"| n_search
n_app -->|"exposes"| n_storage
n_app -->|"loads"| n_llm
n_auth_api -->|"calls"| n_auth_core
n_auth_core -->|"issues tokens"| n_auth_token
n_auth_core -->|"checks codes"| n_auth_verif
n_auth_core -->|"reads users"| n_user
n_profile -->|"updates profile"| n_user
n_knowpost -->|"uses author"| n_user
n_knowpost -->|"requests summary"| n_llm
n_knowpost -->|"invalidates cache"| n_redisson
n_counter -->|"publishes events"| n_kafka
n_relation -->|"writes main data"| n_mysql
n_relation -->|"streams outbox"| n_canal
n_canal -->|"forwards events"| n_kafka
n_kafka -->|"consumed by"| n_counter
n_kafka -->|"consumed by"| n_relation
n_search -->|"queries index"| n_es
n_search -->|"consumes changes"| n_canal
n_knowpost -->|"stores content"| n_mysql
n_knowpost -->|"emits changes"| n_canal
n_storage -->|"presigns upload"| n_oss
n_auth_token -->|"stores refresh"| n_redisson
n_auth_verif -->|"stores codes"| n_redisson
n_auth_core -->|"audits login"| n_mysql
n_common -.->|"shared persistence"| n_mysql
n_common -.->|"formats messages"| n_kafka
n_search -.->|"rebuilds from source"| n_mysql
n_llm -.->|"retrieves context"| n_es

click n_app "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/ZhiGuangApplication.java"
click n_global_exc "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/common/web/GlobalExceptionHandler.java"
click n_common "https://github.com/g-pegasus/zhiguang_be/tree/main/src/main/java/com/tongji/common"
click n_auth_api "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/auth/api/AuthController.java"
click n_auth_core "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/auth/service/AuthService.java"
click n_auth_token "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/auth/token/JwtService.java"
click n_auth_verif "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/auth/verification/VerificationService.java"
click n_profile "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/profile/api/ProfileController.java"
click n_user "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/user/domain/User.java"
click n_knowpost "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/knowpost/api/KnowPostController.java"
click n_knowpost_ai "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/knowpost/api/KnowPostAiController.java"
click n_counter "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/counter/api/CounterController.java"
click n_relation "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/relation/api/RelationController.java"
click n_search "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/search/api/SearchController.java"
click n_storage "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/storage/api/StorageController.java"
click n_llm "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/llm/LlmConfig.java"
click n_redisson "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/config/RedissonConfig.java"
click n_kafka "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/counter/event/CounterEventProducer.java"
click n_es "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/config/ElasticsearchConfig.java"
click n_oss "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/storage/config/OssProperties.java"
click n_mysql "https://github.com/g-pegasus/zhiguang_be/blob/main/db/schema.sql"
click n_canal "https://github.com/g-pegasus/zhiguang_be/blob/main/src/main/java/com/tongji/relation/outbox/CanalKafkaBridge.java"

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 n_app,n_global_exc,n_common toneBlue
class n_auth_api,n_auth_core,n_auth_token,n_auth_verif,n_profile,n_user,n_knowpost,n_knowpost_ai,n_counter,n_relation,n_search,n_storage,n_llm toneAmber
class n_redisson,n_kafka,n_es,n_oss,n_mysql,n_canal toneMint
```

## Components

### Application

Spring Boot entrypoint and shared web/runtime concerns

- [ZhiGuang](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/ZhiGuangApplication.java): spring-boot app · Main application entrypoint · `src/main/java/com/tongji/ZhiGuangApplication.java`
- [Errors](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/common/web/GlobalExceptionHandler.java): web advice · Global exception mapping and business error model · `src/main/java/com/tongji/common/web/GlobalExceptionHandler.java`
- [Common util](https://github.com/g-pegasus/zhiguang_be/tree/HEAD/src/main/java/com/tongji/common): shared helpers · Shared exception codes and outbox message utilities · `src/main/java/com/tongji/common`

### Business domains

Core modular-monolith subdomains

- [Auth API](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/auth/api/AuthController.java): security api · Login, registration, token refresh, logout, password reset · `src/main/java/com/tongji/auth/api/AuthController.java`
- [Auth service](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/auth/service/AuthService.java): security core · Authentication orchestration and security configuration · `src/main/java/com/tongji/auth/service/AuthService.java`
- [JWT store](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/auth/token/JwtService.java): token service · JWT creation plus refresh-token storage in Redis · `src/main/java/com/tongji/auth/token/JwtService.java`
- [Verification](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/auth/verification/VerificationService.java): code service · Verification code send/check flow backed by Redis · `src/main/java/com/tongji/auth/verification/VerificationService.java`
- [Profile](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/profile/api/ProfileController.java): user profile · User profile read and patch operations · `src/main/java/com/tongji/profile/api/ProfileController.java`
- [User model](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/user/domain/User.java): account domain · User master data and persistence layer · `src/main/java/com/tongji/user/domain/User.java`
- [KnowPost](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/knowpost/api/KnowPostController.java): content domain · Knowledge post draft, publish, visibility, feed, and AI-assisted content APIs · `src/main/java/com/tongji/knowpost/api/KnowPostController.java`
- [Post AI](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/knowpost/api/KnowPostAiController.java): content ai · Description generation and RAG entrypoints for posts · `src/main/java/com/tongji/knowpost/api/KnowPostAiController.java`
- [Counter](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/counter/api/CounterController.java): interaction domain · Like/favorite/follow counters and action ingestion · `src/main/java/com/tongji/counter/api/CounterController.java`
- [Relation](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/relation/api/RelationController.java): graph domain · Follow/unfollow relations with outbox-based consistency · `src/main/java/com/tongji/relation/api/RelationController.java`
- [Search](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/search/api/SearchController.java): read model · Search and suggest APIs backed by Elasticsearch · `src/main/java/com/tongji/search/api/SearchController.java`
- [Storage](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/storage/api/StorageController.java): object storage · OSS presign and upload access control · `src/main/java/com/tongji/storage/api/StorageController.java`
- [LLM/RAG](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/llm/LlmConfig.java): ai service · Post summarization and retrieval-augmented generation services · `src/main/java/com/tongji/llm/LlmConfig.java`

### Infrastructure

Datastores, search, messaging, object storage, and AI integration

- [Redis](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/config/RedissonConfig.java): cache client · Shared Redis integration for tokens, cache, counters, and hot data · `src/main/java/com/tongji/config/RedissonConfig.java`
- [Kafka](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/counter/event/CounterEventProducer.java): event bus · Async event backbone for counter and outbox-driven flows · `src/main/java/com/tongji/counter/event/CounterEventProducer.java`
- [Elasticsearch](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/config/ElasticsearchConfig.java): search engine · Content index and suggest backend · `src/main/java/com/tongji/config/ElasticsearchConfig.java`
- [OSS](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/storage/config/OssProperties.java): object store · Alibaba Cloud object storage for direct uploads · `src/main/java/com/tongji/storage/config/OssProperties.java`
- [MySQL](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/db/schema.sql): primary db · System of record for users, content, relations, logs, and outbox · `db/schema.sql`
- [Canal](https://github.com/g-pegasus/zhiguang_be/blob/HEAD/src/main/java/com/tongji/relation/outbox/CanalKafkaBridge.java): binlog bridge · Binlog-driven bridge from outbox changes to Kafka consumers · `src/main/java/com/tongji/relation/outbox/CanalKafkaBridge.java`

## Connections

- ZhiGuang → Errors: handles errors · Application-wide request failure handling
- ZhiGuang → Auth API: exposes · Bootstraps the authentication endpoints
- ZhiGuang → Profile: exposes · Bootstraps the profile endpoints
- ZhiGuang → KnowPost: exposes · Bootstraps the content endpoints
- ZhiGuang → Counter: exposes · Bootstraps the interaction endpoints
- ZhiGuang → Relation: exposes · Bootstraps the relation endpoints
- ZhiGuang → Search: exposes · Bootstraps the search endpoints
- ZhiGuang → Storage: exposes · Bootstraps the storage endpoints
- ZhiGuang → LLM/RAG: loads · Initializes AI/RAG services
- Auth API → Auth service: calls · Controller delegates to authentication service
- Auth service → JWT store: issues tokens · Creates JWTs and persists refresh tokens
- Auth service → Verification: checks codes · Validates verification code flows
- Auth service → User model: reads users · Authenticates against user master data
- Profile → User model: updates profile · Reads and patches user data
- KnowPost → User model: uses author · Resolves post ownership and author data
- KnowPost → LLM/RAG: requests summary · Uses AI for description generation and RAG
- KnowPost → Redis: invalidates cache · Feed and content cache coordination
- Counter → Kafka: publishes events · Action events enter the async counter pipeline
- Relation → MySQL: writes main data · Transactional relation state and outbox records
- Relation → Canal: streams outbox · Binlog change capture for eventual consistency
- Canal → Kafka: forwards events · Outbox changes become Kafka messages
- Kafka → Counter: consumed by · Aggregation and rebuild consumers update derived counters
- Kafka → Relation: consumed by · Relation event processor updates derived views
- Search → Elasticsearch: queries index · Search and suggest read from Elasticsearch
- Search → Canal: consumes changes · Search index is synced from outbox-driven events
- KnowPost → MySQL: stores content · Knowledge posts are written to the system of record
- KnowPost → Canal: emits changes · Content changes flow into async sync pipelines
- Storage → OSS: presigns upload · Generates direct-upload authorization for OSS
- JWT store → Redis: stores refresh · Refresh-token whitelist and revocation state
- Verification → Redis: stores codes · Verification codes and expiry state
- Auth service → MySQL: audits login · Login logs and related auth records
- Common util → MySQL: shared persistence · Common outbox and error-related data helpers support database-backed flows
- Common util → Kafka: formats messages · Shared outbox message utilities support event publication
- Search → MySQL: rebuilds from source · Index initialization and backfill use business data as source
- LLM/RAG → Elasticsearch: retrieves context · RAG query service can use indexed knowledge as retrieval source
