How trae-ai/stream-to-river works
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