# cuixueshe/earthworm architecture

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

- Interactive diagram: https://gitdiagram.com/cuixueshe/earthworm
- Repository: https://github.com/cuixueshe/earthworm

## Overview

以下是为这位高级软件工程师制作系统设计图的详细说明，基于当前项目的文件结构及 README 所提供的信息。该项目是一个全栈应用，将前端（客户端）和后端（API 服务）以及相关工具模块（比如数据库迁移、数据 SDK、文档以及课程数据处理工具）集成在一个 monorepo 中进行管理，采用 pnpm 作为包管理工具，并依赖 Docker Compose 来管理数据库、Redis、以及 Logto 用户系统。

##### 主要组件：
- 后端服务（API）：位于 apps/api 目录，采用 NestJS 框架，实现了多个业务模块（如 course、course-pack、membership、user、logto、cron-job 等）。通过 .env 文件配置数据库（Postgres）、Redis 等外部依赖。
- 前端服务（客户端）：位于 apps/client 目录，使用 Vue/Nuxt 框架构建，通过多个页面、组件、Store 和 composables 实现用户交互，如答题、课程展示、排名等功能。
- 数据库：主要是 Postgres，用于存储后台数据。项目中还包含数据库迁移和初始化工具（packages/db）。
- 缓存/消息队列：Redis 用于加速数据访问与队列处理（通过配置文件在 API 内被调用）。
- 身份认证与授权系统：依赖于 Logto，项目中有 logto 模块用于处理用户认证。
- Docker Compose 服务：通过 docker-compose.yml 管理数据库、Redis 及 Logto 等容器化服务。
- 辅助工具包：
- packages/db：用于数据库相关的操作与管理，包含 SQL 脚本和迁移工具。
- packages/game-data-sdk：处理与课程包和学习活动相关的业务逻辑，并包含单元测试。
- packages/schema：存储数据 schema 定义，作为整个系统的数据契约基础。
- packages/docs：基于 VitePress 构建项目文档，方便贡献者了解项目体系和开发流程。
- packages/xingrong-courses：提供课程数据的处理、导入及解析 PDF 功能。

##### 组件间关系和交互：
- 前端（客户端）通过 HTTP API 与后端服务（NestJS API）进行数据交互，获取课程、用户进度、课件数据等。
- 后端服务在处理前端请求时，通过各个微模块（如 course、membership、user 等）执行业务逻辑，同时与 Postgres 数据库交互，或者操作 Redis 进行缓存处理。
- 用户认证部分由 Logto 模块提供，该模块为用户提供单点登录和身份验证，并与前/后端均存在集成痕迹。
- Docker Compose 环境确保数据库、Redis 和 Logto 等组件实时启停，方便本地开发与测试。
- 辅助工具包（如数据库迁移和课程数据 SDK）在后端启动前参与数据的初始化和更新操作。

##### 建议绘制系统设计图时包含以下细节：
a. 将系统拆分为多个主要逻辑块：前端客户端、后端 API 服务、数据库、缓存（Redis）、认证服务(Logto)及其它工具模块。
b. 利用清晰的标签标明每个组件，如“前端（Nuxt/Vue）”、“后端（NestJS）”、“Postgres 数据库”、“Redis 缓存”、“Logto 身份认证”、“DB 工具包”、“文档系统”等。
c. 使用方向箭头展示数据流和依赖关系：
- 前端发送请求到后端。
- 后端与数据库和 Redis 进行数据存取。
- 后端调用 Logto 模块进行用户验证。
- 部署流程中，也可显示 Docker Compose 管理的各个容器组件。
d. 使用不同的颜色或图形（如矩形表示服务、云形表示外部依赖）来区分不同类型的组件。
e. 可在图中标出用于测试和 CI/CD 的工作流脚本（例如引用 .github/workflows/ci.yaml）以及构建和发布脚本（scripts/release.ts）。

##### 为全栈应用的架构图定制建议：
- 强调前后端分离：说明前端（应用 UI 层）与后端 API 之间的 RESTful 或 GraphQL 数据交互。
- 对后端内部进行模块划分：展示如何将业务功能拆分为多个子模块（如课程、排名、会员、用户进度等）。
- 针对数据库和缓存的交互：显示系统如何结合 postgres 和 redis 进行存储和缓存策略。
- 指出 Docker 组件：在部署或开发环境中如何利用 Docker Compose 管理各个服务。

##### 最终图示应包括：
- 每个组件均带有明确标签。
- 箭头指示数据流及依赖方向（例如：客户端 → API → 数据库/Redis）。
- 使用颜色或不同形状来区分微服务模块、外部依赖和工具包。
- 如果可能，添加注释区分开发、测试和生产环境流程（例如数据库初始化、自动化测试流程等）。

这样设计的系统架构图能够帮助团队成员清晰地了解每个子系统的职责、组件之间如何交互以及项目内部的依赖关系，满足项目开发和后续维护需求。

希望这份详细说明能为系统设计图的制作提供清晰指导，也方便在未来讨论架构优化或集成新功能时作为参考。

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% 前端客户端
    subgraph "前端客户端"
        FE["前端（Nuxt/Vue）"]:::frontend
        LT_Client["Logto身份认证 (客户端)"]:::external
    end

    %% 后端API服务
    subgraph "后端 API 服务"
        BE["后端（NestJS API）"]:::backend
        LT_API["Logto身份认证 (API)"]:::external
    end

    %% 数据库层
    subgraph "数据库层"
        DB["Postgres数据库"]:::external
        DB_Tool["数据库迁移工具"]:::tool
    end

    %% 缓存与队列
    subgraph "缓存/消息队列"
        REDIS["Redis缓存"]:::external
    end

    %% 辅助工具模块
    subgraph "辅助工具模块"
        GS["课程数据 SDK"]:::tool
        DS["数据 Schema"]:::tool
        DOC["文档系统"]:::tool
        COURSE["课程数据处理工具"]:::tool
    end

    %% Docker Compose管理
    DOCKER["Docker Compose管理"]:::compose

    %% 组件间交互
    FE -->|"HTTP请求"| BE
    BE -->|"数据库操作"| DB
    BE -->|"缓存处理"| REDIS
    FE -->|"用户认证"| LT_Client
    BE -->|"身份验证"| LT_API

    BE -->|"调用"| GS
    BE -->|"使用"| DS
    BE -->|"调用"| COURSE

    DOCKER -->|"管理"| DB
    DOCKER -->|"管理"| REDIS
    DOCKER -->|"管理"| LT_API

    %% 组件样式定义
    classDef frontend fill:#AEDFF7,stroke:#1B75BC,stroke-width:2px;
    classDef backend fill:#C8F7C5,stroke:#3AA655,stroke-width:2px;
    classDef external fill:#F7D6AE,stroke:#D97E3C,stroke-width:2px;
    classDef tool fill:#E4DAF7,stroke:#6B3EAA,stroke-width:2px;
    classDef compose fill:#FFF5BA,stroke:#E2A900,stroke-width:2px;

    %% Click事件
    click FE "https://github.com/cuixueshe/earthworm/tree/main/apps/client"
    click BE "https://github.com/cuixueshe/earthworm/tree/main/apps/api"
    click DB_Tool "https://github.com/cuixueshe/earthworm/tree/main/packages/db"
    click DOCKER "https://github.com/cuixueshe/earthworm/blob/main/docker-compose.yml"
    click REDIS "https://github.com/cuixueshe/earthworm/blob/main/docker-compose.yml"
    click LT_API "https://github.com/cuixueshe/earthworm/tree/main/apps/api/src/logto"
    click LT_Client "https://github.com/cuixueshe/earthworm/blob/main/apps/client/plugins/logto.ts"
    click GS "https://github.com/cuixueshe/earthworm/tree/main/packages/game-data-sdk"
    click DS "https://github.com/cuixueshe/earthworm/tree/main/packages/schema"
    click DOC "https://github.com/cuixueshe/earthworm/tree/main/packages/docs"
    click COURSE "https://github.com/cuixueshe/earthworm/tree/main/packages/xingrong-courses"
```
