---
title: "Shuke"
source: "README.md"
---

> Part of [Overview](/overview/llms.txt). Every page: [llms.txt](/llms.txt).

# Shuke (codename) — 每天十分钟，把复杂的事讲清楚

> Working codename: **Shuke / 述刻**. Final app name, branding and domain are TBD; everything brand-specific lives behind a single token layer so it can be swapped later.

The repo follows the [botgumi](https://github.com/xieweizhi/botgumi) template, version `0.0.0+1b57100` (see `.botgumi.json`): agent instructions in `AGENTS.md` and `.claude/agents/`, the design stages in `design/`, docs for agents in `docs/`, the checklists in `docs/checklists/`. Shuke predates the template, so its tracks keep their own CI and the design gates are retroactive (`design/README.md`).

A spoken-expression trainer (multilingual: English and Simplified Chinese first, built for more). The user reads a short article, retells it aloud in their own words, gets AI feedback with **one thing to change**, retells it compressed, and sees a measurable delta. iOS-first, subscription business model with a hard paywall after a free diagnostic.

## Repository layout

| Path | What | Stack | Owner PR label |
|---|---|---|---|
| `docs/` | PRD, review, decisions (ADRs), API contract, prototype references | Markdown / OpenAPI 3.1 | `docs` |
| `design/` | Hi-fi design: tokens, screens (HTML), flows, states, onboarding, paywall prototype, data-binding tables; the five botgumi stages on top (`brand/`, `system/`, `lofi/`, `hifi/`, `screenshots/`, see `design/README.md`), checked by `node design/check.mjs` | Static HTML/CSS/JS, stdlib Python generators | `design` |
| `backend/` | API + AI pipeline | Cloudflare Workers, Hono, D1, R2, KV, Queues, Workers AI; dynamic AI providers (ASR / LLM / TTS) | `backend` |
| `landing/` | Super simple landing page | TanStack Start, deployed to Cloudflare | `landing` |
| `ios/` | Native iOS app | Swift 6, SwiftUI, iOS 17+, XcodeGen, RevenueCat (StoreKit 2), Sign in with Apple | local `ios/scripts/ci.sh` (no GitHub CI) |
| `dashboard/` | Operator dashboard for content ops (sources, generation, review queue, providers, quality) | TanStack Start, Cloudflare Access, talks to `/v1/admin/*` | `dashboard` |
| `docs/public/` | Docs for agents, built from every page in `docs/manifest.json` (`pnpm docs:build`) | `@botgumi/docs`, Cloudflare Worker behind Access | `docs` |

## Source of truth (read in this order)

1. `docs/prd/prd-v1.0-extracted.txt` — the original PRD (Chinese).
2. `docs/prd/PRD-REVIEW.md` — TPM review: gaps, risks, what changed.
3. `docs/decisions/ADR-001-product-decisions.md` — every open decision in the PRD, resolved. **Binding.**
4. `docs/api/openapi.yaml` — the API contract between `ios/` and `backend/`. **Binding.** Change it via PR with both sides updated.
5. `docs/decisions/ADR-002-content-operations.md` + `docs/api/openapi-admin.yaml` — automated content supply (licensed sources + AI originals, QA, auto-publish) and the admin API the dashboard consumes. **Binding.**
6. `design/README.md` — design system and screen specs (produced by the design track).

## Working agreement

- Trunk is `main`. All work lands via PR from a branch named `<track>/<topic>` (e.g. `backend/sessions-pipeline`).
- Every PR: description (what / why / how tested), passing CI for its track, no cross-track edits unless the PR says so.
- The API contract is the integration boundary. If a client needs a field, add it to `docs/api/openapi.yaml` first.
- Every visible data point in the app must be traceable to an API field or a documented local state (see `design/data-binding.md`).
- No fake data in production paths. Seeded demo content is explicitly labelled `source: "seed"`.
- The product is multilingual. UI locales in v1: `en`, `zh-Hans`; practice/content languages in v1: `en`, `zh-Hans` (see ADR-001 D13). Code, commits and docs are in English.

## Docs

Every page about this app is Markdown in this repo, listed by module in `docs/manifest.json` and built into
`docs/public/`: `/llms.txt` (every page by module), `/llms-full.txt`, each module's `llms.txt` and `llms-full.txt`,
and `index.md` for every page. Agents read `docs/public/llms.txt` first. `pnpm docs:dev` serves them locally,
`pnpm docs:build` rewrites `docs/public/` (commit it with the change) and `pnpm docs:check` fails when it is stale;
`docs/README.md` says how they are hosted. Install with `pnpm install` at the repo root; botgumi's packages come from
GitHub Packages, so set `NODE_AUTH_TOKEN` to a token with `read:packages` first (`.npmrc`). CI runs the docs check.

## Getting started

```bash
# backend
cd backend && pnpm install && pnpm dev

# landing
cd landing && pnpm install && pnpm dev

# ios
cd ios && xcodegen generate && open Shuke.xcodeproj

# docs and design checks, at the repo root (botgumi's packages: a token with read:packages)
gh auth refresh -s read:packages && export NODE_AUTH_TOKEN=$(gh auth token)
pnpm install && pnpm docs:check && pnpm design:check
```