# trae-ai/stream-to-river architecture

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

- Interactive diagram: https://gitdiagram.com/trae-ai/stream-to-river
- Repository: https://github.com/trae-ai/stream-to-river

## Overview

##### Project type and purpose
- This is a full-stack, front-end/back-end separated microservice system (“Streams to River V2”) for English learning.
- Purpose: record/extract/manage words, sentences, contexts; schedule review via Ebbinghaus curve; integrate LLM, speech recognition (ASR), image-to-text, real-time chat.

##### File structure
- Top-level directories:
- client/ (React/TypeScript/mini-app front end)
- apiservice/ (HTTP API layer built on Hertz)
- rpcservice/ (business logic RPC layer built on Kitex)
- idl/ (Thrift definitions)
- dockerfile/ (Docker images, compose, etc.)
- internal/ (integration test suites)
- utils, .github, .trae, config files, docs, LICENSE
- Pattern: layered microservices, clear separation of concerns, CI/CD workflows, containerization.

##### README for additional insights
- Architecture layers:
1. API Service Layer (Hertz HTTP, REST/SSE/WebSocket)
2. RPC Service Layer (Kitex)
3. Data Access Layer (MySQL, Redis)
4. Intelligent Processing Layer (LLM, ASR, Image2Text via external services/Coze)

- Client (Web/Mobile front end)
- API Service Layer (Hertz based microservices)
- RPC Service Layer (Kitex based microservices; e.g., chat, words, user)
- Data Access Layer: MySQL database, Redis cache
- External AI Services: LLM provider (Coze/Volcano Ark), ASR provider, Vision model
- Supporting infra: Service Discovery, Configuration Service, OpenTelemetry collector
- Orchestration: Docker-Compose / Kubernetes
b. Relationships & interactions:
- Client ⇄ HTTP/REST, SSE, WebSocket ⇄ API Service
- API Service ⇄ RPC calls ⇄ RPC Service
- RPC Service ⇄ Data Access (CRUD via MySQL, Redis)
- RPC Service ⇄ External AI services (LLM, ASR, Vision)
- All services emit metrics to OpenTelemetry; config pulled from dynamic config service; JWT flows for auth.
c. Architectural patterns & design principles:
- Layered architecture (presentation, API, RPC, data, external)
- Microservices (each business domain in separate Kitex service)
- Asynchronous streaming (SSE/WebSocket for chat & ASR)
- Caching (Redis) to reduce DB load
- Service discovery & dynamic configuration for resilience
- CI/CD via GitHub Actions, Docker containers
d. Key technologies/frameworks:
- Front end: React/TypeScript, Taro (mini-app), LESS, pnpm
- API: Go + Hertz, JWT, SSE, WebSocket
- RPC: Go + Kitex, Thrift IDL
- DB: MySQL, Redis
- AI/ML: Coze LLM, Volcano Ark ASR & Vision models
- Monitoring: OpenTelemetry collector
- Container: Docker, Docker-Compose

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        Client["Client (Web/Mobile)"]:::frontend
    end

    %% API Service Layer
    subgraph "API Service Layer"
        HertzAPI["Hertz API Gateway"]:::api
        Router["Router"]:::api
        Handler["Biz Handlers"]:::api
        ASR["ASR Handler"]:::api
        Image2Text["Image2Text Handler"]:::api
        ConfigAPI["Config Loader"]:::api
    end

    %% RPC Service Layer
    subgraph "RPC Service Layer"
        KitexRPC["Kitex RPC Gateway"]:::rpc
        ChatService["ChatService"]:::rpc
        WordsService["WordsService"]:::rpc
        LLMService["LLM ArkModel"]:::rpc
        ConfigRPC["Config Loader"]:::rpc
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        MySQL["MySQL"]:::db
        Redis["Redis"]:::db
    end

    %% External AI Services
    subgraph "External AI Services"
        ExternalLLM["Coze LLM"]:::ext
        ExternalASR["ASR Provider (Volcano Ark)"]:::ext
        ExternalVision["Vision Model (Volcano Ark)"]:::ext
    end

    %% Infrastructure & Observability
    subgraph "Infrastructure & Observability"
        EtcD["etcd (Service Discovery)"]:::infra
        ConfigService["Config Service"]:::infra
        OTel["OpenTelemetry Collector"]:::infra
        DockerCompose["Docker-Compose"]:::infra
    end

    %% CI/CD
    subgraph "CI/CD Pipeline"
        GithubActions["GitHub Actions"]:::infra
    end

    %% Relationships
    Client -->|HTTP/REST| HertzAPI
    HertzAPI --> Router
    Router --> Handler
    Handler -->|RPC| KitexRPC
    Handler --> ASR
    ASR -->|REST API| ExternalASR
    Handler --> Image2Text
    Image2Text -->|REST API| ExternalVision
    Handler --> ConfigAPI

    Router --> KitexRPC
    KitexRPC --> ChatService
    KitexRPC --> WordsService
    KitexRPC --> LLMService
    KitexRPC --> ConfigRPC

    WordsService --> MySQL
    WordsService --> Redis

    ChatService -->|RPC| ExternalLLM
    LLMService -->|RPC| ExternalLLM

    %% Service Discovery & Config & Metrics
    HertzAPI -->|register| EtcD
    KitexRPC -->|register| EtcD
    ChatService -->|register| EtcD
    WordsService -->|register| EtcD
    LLMService -->|register| EtcD

    HertzAPI -->|fetch| ConfigService
    KitexRPC -->|fetch| ConfigService
    ChatService -->|fetch| ConfigService
    WordsService -->|fetch| ConfigService
    LLMService -->|fetch| ConfigService

    HertzAPI -.->|metrics| OTel
    KitexRPC -.->|metrics| OTel
    ChatService -.->|metrics| OTel
    WordsService -.->|metrics| OTel
    LLMService -.->|metrics| OTel

    %% CI/CD Flow
    GithubActions --> DockerCompose

    %% Click Events
    click Client "https://github.com/trae-ai/stream-to-river/tree/main/client/"
    click HertzAPI "https://github.com/trae-ai/stream-to-river/blob/main/apiservice/main.go"
    click Router "https://github.com/trae-ai/stream-to-river/blob/main/apiservice/router.go"
    click Handler "https://github.com/trae-ai/stream-to-river/tree/main/apiservice/biz/handler/"
    click ASR "https://github.com/trae-ai/stream-to-river/blob/main/apiservice/biz/asr/asr.go"
    click Image2Text "https://github.com/trae-ai/stream-to-river/blob/main/apiservice/biz/image2text/image2text.go"
    click ConfigAPI "https://github.com/trae-ai/stream-to-river/blob/main/apiservice/biz/config/loadconfig.go"
    click KitexRPC "https://github.com/trae-ai/stream-to-river/blob/main/rpcservice/main.go"
    click ChatService "https://github.com/trae-ai/stream-to-river/tree/main/rpcservice/biz/chat/"
    click WordsService "https://github.com/trae-ai/stream-to-river/tree/main/rpcservice/biz/words/"
    click LLMService "https://github.com/trae-ai/stream-to-river/blob/main/rpcservice/biz/llm/arkmodel.go"
    click ConfigRPC "https://github.com/trae-ai/stream-to-river/blob/main/rpcservice/biz/config/loadconfig.go"
    click idl "https://github.com/trae-ai/stream-to-river/tree/main/idl/"
    click MySQL "https://github.com/trae-ai/stream-to-river/blob/main/rpcservice/dal/mysql/init.go"
    click Redis "https://github.com/trae-ai/stream-to-river/blob/main/rpcservice/dal/redis/init.go"
    click ExternalLLM "https://github.com/trae-ai/stream-to-river/blob/main/rpcservice/biz/chat/coze/coze.go"
    click EtcD "https://github.com/trae-ai/stream-to-river/blob/main/dockerfile/etcd.conf.yml"
    click OTel "https://github.com/trae-ai/stream-to-river/blob/main/dockerfile/otel-collector-config.yaml"
    click DockerCompose "https://github.com/trae-ai/stream-to-river/blob/main/dockerfile/docker-compose.yaml"
    click GithubActions "https://github.com/trae-ai/stream-to-river/blob/main/.github/workflows/go.yml"

    %% Styles
    classDef frontend fill:#E0F7FA,stroke:#006064;
    classDef api fill:#E8F5E9,stroke:#1B5E20;
    classDef rpc fill:#FFF3E0,stroke:#EF6C00;
    classDef db fill:#CFD8DC,stroke:#37474F;
    classDef ext fill:#F3E5F5,stroke:#6A1B9A;
    classDef infra fill:#ECEFF1,stroke:#90A4AE;
```
