跳到主要内容

架构

这些页面是跨代码库的系统图:它们从头到尾说明一个核心 ChurchApps 系统如何运作,涵盖各个应用、API 模块和共享库,而不是某一个项目如何设置。在修改某个系统的行为之前,请先阅读这些页面;若要让某个项目运行起来,请阅读设置;若要查阅端点级别的参考资料,请查看 API 部分。

生态系统概览​

ChurchApps 包含约 20 个独立的代码库(并非单一仓库)。客户端应用通过 HTTPS 和 WebSocket 与一组较小的后端 API 通信,并通过以 @churchapps 为作用域发布的 npm 包共享代码。

┌────────────────────────────────┐            ┌──────────────────────────────────────────────┐
│ Clients │ │ Api — core modular monolith (AWS Lambda) │
│ │ │ │
│ B1Admin staff dashboard │ HTTPS │ membership attendance content │
│ B1App member portal + │ ─────────▶ │ giving messaging doing │
│ church websites │ │ │
│ B1Checkin check-in kiosk │ ◀───WS───▶ │ one MySQL database per module (6 total) │
│ │ └──────────────────────────────────────────────┘
│ FreePlay TV content player │ ┌──────────────────────────────────────────────┐
└───────────────┬────────────────┘ │ LessonsApi — Lessons.church backend │
│ └──────────────────────────────────────────────┘
│ shared code via npm (@churchapps/*)
▼
helpers (cross-app interfaces) · apphelper (React components) · apihelper (Express/server utilities)

有两条结构性规则决定了本节记录的所有内容:

  1. 模块彼此隔离。 每个 Api 模块都拥有自己的数据库和数据表;其他模块和应用只能通过其 REST 端点访问其数据。参见模块结构。
  2. 共享代码以 npm 包的形式发布。 应用之间不会直接导入彼此的源代码;任何可复用的内容都要通过 @churchapps/helpers、@churchapps/apphelper 或 @churchapps/apihelper 跨越代码库边界。参见共享库。

系统图​

页面涵盖内容涉及范围
通知与提醒任何系统如何告知某人某事:两个分发入口、渠道升级链以及提醒引擎Api(messaging)、B1Admin、B1App
实时架构支撑聊天、在线状态和应用内推送的 WebSocket 投递框架Api(messaging)、所有网页应用
网页推送通知浏览器推送渠道:VAPID 密钥、订阅存储、投递Api(messaging)、所有网页应用
捐款支付服务商与网关、捐款流程、基金/批次、网关 webhookApi(giving)、apphelper、B1App、B1Admin
活动报名报名的商业模型:参与者类型、选项、折扣码、通过捐款网关付款,以及候补名单Api(content + giving)、B1App、B1Admin
签到自助签到终端与自助签到、出勤数据模型、房间路由、儿童安全层、标签打印B1Checkin、B1App、B1Admin、Api(attendance + membership)
网站构建器页面/区块/元素树、元素类型契约与渲染器、博客、受访问控制的页面、SEO 以及 AI 生成Api(content)、AskApi、helpers/apphelper、B1Admin、B1App
网站路由与多站点请求如何解析到某个教会及特定网站、多站点 siteId 数据模型,以及 Caddy 自定义域名边缘层B1App、Api(membership + content)、B1Admin
集成扩展接口:OAuth、API 密钥、webhook、内容提供方、MCPApi、共享库、外部应用
审计日志与可撤销批次在控制器关键节点默认对每次变更进行审计,以及让导入和批量操作可以撤销的批次层Api(所有模块)、B1Admin、B1Transfer
MinistryStuff付费存储与短信额度服务:共享 JWT 身份、服务密钥 S2S、短信和存储提供方接口、Stripe 计费MinistryStuffApi、MinistryStuffWeb、Api(content + messaging)、短信/apihelper 包、B1Admin
自带存储(BYOS)教会可链接 Google Drive、Dropbox、OneDrive 或兼容 S3 的存储桶,以突破免费的 100MB 上传限制:OAuth 连接、各提供方的上传格式、公开下载重定向Api(content + membership)、helpers/apphelper 包、B1Admin、B1App
内容共享库支撑跨产品用户生成内容的共享资产/投稿核心,以及 B1Admin 服务器管理中仅限员工使用的单一审核队列Api(commons 模块)、B1Admin、WorshipCommons、Lessons.church、FreeShow
提示

当某项变更改变了这些系统的运作方式(而不仅仅是某个应用内的一个页面)时,应在同一项工作中同步更新此处对应的系统图。这样可以让本节始终可靠,成为新贡献者的首要参考。

提案​

这些文档描述的是供审阅的拟议工作,而非现有的产品功能。

提案涵盖内容
Twilio 自带密钥(BYOK)教会自有账户、密钥、服务和电话号码;集成范围、同意、投递、估算以及发布检查
Twilio 教会入驻草案拟议的 B1 注册表单设置、针对特定教会的营销活动示例,以及审批和运营检查清单