Keel source module relationships

All source modules inside the Keel repo + each module’s responsibility / dependencies / artifacts. The reason this doc exists: when a human or AI picks up the codebase, they can see at a glance what every directory does + who consumes its output.

Note: this English version lags behind the zh version. Authoritative layout is in source-modules.md. Top-level dirs after the 2026-05 restructure: sdk/, modules-core/, packages/, modules/, apps/, go/, snack/, cli/, tools/, cloud/, site/, docs/, packaging/.

Name collision warning: keel/docs/modules.md is about the 5 first-class npm modules Keel maintains (WeChat / Alipay / Amap / Jiguang / Umeng). This doc is about the code modules inside the Keel repo (sdk/ + modules-core/ + packages/* + modules/* + cli/

cloud/ etc.).

0. One picture of everything

┌─────────────────────────────────────────────────────────────────────────┐
│                       Keel source module topology                       │
└─────────────────────────────────────────────────────────────────────────┘

【ship binaries】
   keel/build/ios/Keel.xcframework      ← packaging/build-ios.sh
   keel/build/android/keel-sdk.aar      ← packaging/build-android.sh
   appunvs/cloud-build-mobile:latest (Docker)  ← cloud/packaging/build-cloud-build.sh
   keel/go/build/{ios.ipa,android.aab} ← packaging/build-keel-go.sh

【downstream consumers】
   host apps             ←  Keel.xcframework / keel-sdk.aar
   Keel Go tester app    ←  Keel.xcframework / keel-sdk.aar
   build orchestrators   ←  appunvs/cloud-build-mobile:latest (via DockerBuilder)

────────────────────────────────────────────────────────────────────────────

【source modules】

🟦 1. Native SDK source (`source/`)
   A Keel project produced by RN-init; SDK source is folded into the
   main app target:

   source/
   ├─ package.json (name: Keel) + index.js + app.json + babel.config.js + metro.config.js
   ├─ App.tsx + __tests__/                  RN init default
   ├─ ios/
   │  ├─ Keel.xcodeproj/                    single xcodeproj
   │  ├─ Keel/
   │  │  ├─ AppDelegate.swift               RN init container app
   │  │  ├─ Keel.h, Keel.mm                 SDK ObjC++ headers + bridge
   │  │  └─ KeelView.swift                  SDK Swift — KeelView implementation
   │  └─ Podfile
   └─ android/
      ├─ app/src/main/java/com/keel/        RN init MainActivity / MainApplication
      ├─ app/src/main/java/com/appunvs/keel/
      │  ├─ KeelSDK.kt                      SDK global init / handles
      │  └─ KeelView.kt                     SDK FrameLayout — KeelView implementation
      ├─ build.gradle  settings.gradle  gradlew*  gradle.properties

   Artifacts: Keel.xcframework / keel-sdk.aar
   Deps: react-native (RN 0.85.3 via source/package.json)
   Consumers: host apps, keel-go

🟦 1b. Platform npm packages (`packages/<name>/`)
   ├─ keel/                      ← @keel-ai/keel umbrella
   ├─ application/               app metadata (bundle ID / name / version)
   ├─ constants/                 runtime constants (status bar height / platform / simulator)
   ├─ device/                    device info (model / manufacturer / OS)
   ├─ asset/                     bundle asset resolution + remote download
   ├─ font/                      runtime font registration
   ├─ updates/                   OTA client (TS + Swift + Kotlin three parallel implementations)
   ├─ router/                    file-based routing
   ├─ router-metro-plugin/       build-time route discovery
   ├─ modules-core/              Modules API (scaffolding for community native modules)
   ├─ push/                      push registration + send wrapper
   ├─ auth-session/              OAuth 2.0 PKCE
   ├─ apple-signin / google-signin
   ├─ keel-module-{wechat,alipay,amap,umeng}
   ├─ skill/                     Claude Code skill bundle
   ├─ bundle-atlas/              bundle internals visualization
   └─ vscode-keel/               VS Code extension

   Artifacts: one npm package each, with bundled podspec / aar
   Integration: host app `npm install @keel-ai/<name>` + standard RN autolink

🟦 1c. Scaffolding (independent npm packages)
   ├─ create-keel-project/           `npm create keel-project my-app`
   └─ create-keel-module/        `npm create keel-module my-mod`

   Follows the Expo create-* convention, separate from @keel-ai/cli.

🟦 2. CLI (`cli/`, npm publishable `@keel-ai/cli`)
   └─ cli/
      ├─ src/commands/
      │  ├─ build.ts              trigger remote Cloud Build
      │  ├─ doctor.ts             env self-check
      │  ├─ manifest.ts           inspect / change remote manifest
      │  ├─ publish.ts            upload bundle → Update server
      │  ├─ rollback.ts           rotate "current" pointer
      │  ├─ start.ts              local dev server (metro + QR for Keel Go)
      │  ├─ submit.ts             Submit to 5+2 stores
      │  ├─ dev-client.ts         Dev Client (V1 scaffold; V1.5 real)
      │  ├─ install.ts            RN-aware npm install
      │  ├─ login.ts / logout
      │  └─ stubs.ts              native module stub generator
      ├─ src/api/                 Update / CloudBuild HTTP clients
      └─ src/util/

   Artifacts: bin/keel (npm bin)
   Deps: HTTP to Update server + Cloud Build server
   Consumers: end-user RN developers

🟧 3. Cloud Build (`cloud/`)
   ├─ cloud/build-image/         Docker build context
   │  ├─ Dockerfile
   │  ├─ build-bundle.sh
   │  ├─ metro.config.js
   │  └─ fixture-rn/
   ├─ cloud/cmd/build-server/   HTTP entrypoint
   └─ cloud/internal/cloudbuild/      job queue, runner, artifact

   Artifacts: appunvs/cloud-build-mobile:latest Docker image + keel-build-server
   Consumers: keel/cli/src/commands/build.ts

🟧 4. Update (`cloud/`)
   ├─ cloud/cmd/update-server/   HTTP entrypoint
   └─ cloud/internal/update/     manifest / patch / rollout / blob / monitoring

   Artifacts: keel-update-server
   Deps: SQLite (default) / Postgres + S3-compat (incl. Aliyun OSS) + CDN
   Consumers: Keel runtime + keel cli publish/rollback

🟧 5. Submit (`cloud/internal/submit/`)
   ├─ submit.go + registry_test.go
   └─ drivers/{appstore,googleplay,huawei,xiaomi,oppo,vivo,yyb}/

   Artifacts: library (no standalone binary; triggered via `keel submit`)

🟧 Push server (`cloud/cmd/push-server/`)
   Jiguang + Getui dispatcher.

🟪 Companion: Keel Go (tester app)
   └─ go/
      ├─ src/{App,HomeScreen,PreviewScreen,NativeKeelView,ScannerOverlay,recents}.tsx
      ├─ ios/                     Xcode project (links Keel.xcframework)
      └─ android/                 Gradle project (links keel-sdk.aar)

   Artifacts: KeelGo.ipa + keel-go.aab
   Consumers: end-user RN developers

🟪 Companion: Keel Snack (browser playground)
   └─ snack/
      Next.js + Monaco editor + RN Web fallback (importmap → esm.sh RN Web,
      Babel transforms TS+JSX in the browser, zero-server)

🟪 Examples
   └─ apps/examples/0[1-5]-* (5 end-to-end examples)

🟫 Shared lower layers (`cloud/internal/`)
   ├─ keelauth/                  API key / OIDC SSO / RBAC / audit log
   └─ billing/                   subscription / tiers + WeChat Pay / Alipay

🟫 Docs (`docs/`)
   ├─ architecture.md            5-layer product overview
   ├─ source-modules.md          👈 this doc
   ├─ modules.md                 5 first-class npm module specs
   ├─ deployment-sop.md          self-hosted instance ops manual
   ├─ deployment.md              deployment architecture overview
   ├─ enterprise-distribution.md private distribution options
   ├─ update.md / submit.md / build.md
   ├─ governance.md / roadmap.md / pricing.md
   ├─ tutorial.md                zero-to-published tutorial
   ├─ examples.md / keel-go.md / snack.md
   ├─ custom-domain.md / github-actions.md / source-modules.md
   └─ ...

🟫 Packaging (`packaging/`)
   ├─ build-ios.sh               produces Keel.xcframework (operates on source/)
   ├─ build-android.sh           produces keel-sdk.aar (operates on source/)
   ├─ build-fixture.sh           produces RuntimeRoot.jsbundle
   ├─ release.sh                 one-click release collection
   └─ build-keel-go.sh           produces KeelGo ipa + aab

🟫 Site (`site/`)
   Astro 4 marketing site + i18n (zh default / en under /en/)

🟫 Deploy (`cloud/deploy/helm/keel/`)
   Helm chart: update-server + build-server + push-server

1. Per-module SLA / API stability level

Module	Public API	Compatibility commitment
Native SDK	Native class names (KeelView etc.)	semver; breaking changes require major bump
CLI (`@keel-ai/cli`)	Command line + flag table	semver; command renames keep an alias for 1 minor version
Update server	REST endpoints (`/v1/{project}/...`)	Adding endpoints is free; schema changes require v1→v2
Open Monitoring API	`/v1/monitoring/{health,metrics,diagnostics}`	Fixed JSON schema; adding fields is free, changing/removing requires major
Submit drivers	Internal `Submitter` interface	Internally unstable; the CLI flags are the public surface
Cloud Build	HTTP REST (`POST /jobs`)	Same as Update server
Keel Go	UX	Not a public API; end-user experience only

2. Dependency graph (compile-time + runtime)

                           host shell / Keel Go
                                      ↓ embeds
                                Keel SDK binary
                                ↑           ↓ runtime fetch
                      ┌─────────┴───┐   ┌───┴────────┐
                      │ Cloud Build  │  │  Update    │
                      │   server     │  │  server    │
                      └──────┬───────┘  └────┬───────┘
                             ↓ artifact      ↓ blob
                       ┌─────┴──────────────┴─────┐
                       │  OSS / S3 + CDN          │
                       └──────────────────────────┘
                                   ↑ submit upload
                            ┌──────┴────────┐
                            │ Submit drivers│
                            └────────────────┘
                                   ↑
                            (CLI `keel submit ...`)

3. Who can be replaced / spun out independently

Module	Independent	Notes
Native SDK (source/)	❌	KeelView ABI is bound to the host bridge; changing it forces all consumers to recompile
CLI	✅	Pure npm package; releases independently
create-keel-project / -module	✅	Independent npm packages with bundled templates
Update server	✅	Independent Go service + independent DB
Cloud Build server	✅	Independent Go service + Docker daemon
Push server	✅	Independent Go service, fronts Jiguang / Getui
Submit drivers	✅	Each driver is an independent package
Keel Go	✅	Independent RN project; only consumes the SDK binary
Keel Snack	✅	Independent Next.js web app

4. Name disambiguation table

File / concept	What it refers to
`keel/docs/modules.md`	Spec for the 5 first-class npm modules Keel maintains (WeChat / Alipay / Amap / Jiguang / Umeng)
`keel/docs/source-modules.md`	This doc: code modules inside the Keel repo
`keel/sdk/`	SDK source (iOS Swift + Android Kotlin + JNI) → Keel.xcframework / keel-sdk.aar
`keel/modules-core/`	Module framework: Swift Macros + KSP + KeelModule base + KeelInstallContext + cross-platform JSI bridge
`keel/modules/`	`create-keel-module` outputs (5 China-first vendor modules)
`keel/packages/<name>/`	`@keel-ai/*` feature packages (constants/device/font/router/updates/…)
`keel/apps/<name>/`	`create-keel-project` outputs (end-user apps; currently just keel-gallery)
`keel/go/` / `keel/snack/`	First-party tester app (RN) + playground (Next.js)
`@keel-ai/keel` (npm)	User-installed umbrella library (`import { KeelSDK } from '@keel-ai/keel'`); source in `keel/sdk/`
`Keel.xcframework` / `keel-sdk.aar`	Native binary SDK artifacts that host apps embed

Editing this doc

Editing this doc = editing architectural facts. Before changes, also update:

architecture’s 5-layer diagram
../README.md’s “5-layer product” section