系统架构总览¶

读者： AI Agent、新成员 — 了解 10 个 repo 的职责边界和协作关系，知道改什么需要动哪个 repo。详细 repo 介绍见 team-ops/repo-overview.md。

一句话定位¶

retaintive 是面向健身工作室的 AI 通话分析 + 线索追踪平台。核心链路： RingCentral 录音 → 语音转文字 → AI 分析 → Dashboard 展示。

系统架构图¶

┌─────────────────────────────────────────────────────────────────┐
│                        外部系统                                  │
│  RingCentral 电话系统    Lark 邮件服务    客户浏览器              │
└────────┬───────────────────┬──────────────────────────────────┘
         │ Webhook 事件       │ Lead 通知邮件
         ▼                   ▼
┌─────────────────┐  ┌────────────────┐
│ ringcentral     │  │ lead-tracking  │
│ Subscription   │  │ IMAP Poller    │
│ Service        │  │ (Lambda)       │
│ (Webhook 路由)  │  └───────┬────────┘
└────────┬────────┘          │ 写入
         │                   ▼
         │ telephony SQS  ┌──────────────────────────────────┐
         │ message SQS    │         DynamoDB 数据层            │
         ▼                │  LeadTracking-v2  (Lead 数据)     │
┌─────────────────────────┤  call-analysis    (AI 分析结果)   │
│ callytics-              │  call-events      (原始通话事件)  │
│ infrastructure          │  MessageStore     (SMS/VM 消息)   │
│ (AI 分析工厂)            │  Conversations    (会话聚合)      │
│                         └──────────────────────────────────┘
│  TranscribeProcessor         │ DDB Streams / 直写
│  ResultProcessor (AI)        ▼
│  MessageProcessor       ┌──────────────────┐
│  ContactsAnalyzer  ───► │  Neon PostgreSQL  │
│  NeonSync               │  (contacts/calls/ │
└─────────────────────────│   messages 表)    │
                          └────────┬─────────┘
                                   │ 读取
                          ┌────────▼─────────────────┐
                          │  studio-website-monorepo  │
                          │  API (Hono + Lambda)      │
                          │  Web (Vue 3 SPA)          │
                          └───────────────────────────┘
                                   │
                          ┌────────▼──────────────────┐
                          │  Cloudflare Pages          │
                          │  studio.retaintive.ai      │
                          └───────────────────────────┘

Repo 职责速查¶

Agent 使用指引： 收到任务时，先找到对应的 repo，再读该 repo 的 CLAUDE.md。

Repo	一句话职责	主要入口文件	改这里会影响
`ringcentralSubscriptionService`	RC Webhook 接收 + 事件路由	`CLAUDE.md`, `src/handlers/`	callytics SQS 消息格式
`callytics-infrastructure`	AI 通话分析 + 消息处理 + CDK 基础设施	`CLAUDE.md`, `lib/stacks/`, `lambda/`	DynamoDB schema, Neon写入, AI 分析输出
`studio-website-monorepo`	Dashboard 前端 + API 后端	`CLAUDE.md`, `apps/api/src/`, `apps/web/src/`	用户可见的所有 UI 和 API
`lead-tracking`	邮件 Lead 采集 → DynamoDB	`src/handler.ts`	LeadTracking-v2 表数据
`callytics-common`	共享工具库（错误类/日志/重试）	`src/`	所有引用该包的 repo
`rcConnectionChecker`	内部 RC 账户监控面板	`src/`	内部工具，不影响产品
`cloudflare-github-webhook-rerouter`	GitHub 事件 → Lark 群通知	`src/index.ts`	CI/部署告警通知
`landingPage`	新版官网	`app/`	retaintive.com 主页
`retaintive.ai.landingpage`	retaintive.ai 官网	`app/`	retaintive.ai 主页
`docs`	组织内部文档	`docs/`	文档，不影响系统

跨 Repo 边界（最容易踩坑的地方）¶

共享 SQS 队列名称（硬编码）¶

ringcentralSubscriptionService 写入、callytics-infrastructure 消费：

队列	格式
通话处理队列	`call-analytics-{env}-transcribe-queue-{region}`
消息处理队列	`call-analytics-{env}-message-queue-{region}`

改队列名时，两个 repo 必须同步更新。

共享 DynamoDB 表（跨 repo 读写）¶

表	写入方	读取方
`call-analytics-{env}-call-analysis-{region}`	callytics-infrastructure	studio-api, ContactsAnalyzer
`LeadTracking-v2-{region}`	lead-tracking, callytics-infrastructure	studio-api, ContactsAnalyzer
`MessageStore-{region}`	callytics-infrastructure	studio-api

新跨服务资源¶

新增共享资源时，用 SSM Parameter Store（不要硬编码）：

// 生产方：/callytics/{env}/category/resource-name
// 消费方：冷启动时读取并缓存

数据流总览¶

完整的通话分析流程见 cross-repo-features/call-analytics-pipeline.md。

环境¶

环境	API	前端	AWS Region
test	`studio-api-test.retaintive.ai`	Cloudflare Pages (test)	us-west-2
pre	`studio-api-pre.retaintive.ai`	Cloudflare Pages (pre)	us-east-2
prod	`studio-api.retaintive.ai`	`studio.retaintive.ai`	us-east-1