GraceChords
GraceChords is a worship songbook platform for churches and worship teams. It
manages a ChordPro song catalog with fast search,
key transposition, setlist and songbook building, PDF/PPTX export, a full-screen
worship mode, and daily Bible readings.
New here? Jump to the app you're working on: web
or mobile. This root README is the map; each app's
README is the manual.
What's in this repo
This is an npm-workspaces monorepo. Platform-agnostic logic is factored into
shared packages so the web and native apps can consume the same parser,
transposition, RBAC, and Supabase wiring.
GraceChords/
├── apps/
│ ├── web/ @gracechords/web — React + Vite SPA (production site)
│ ├── mobile/ @gracechords/mobile — Expo / React Native app (iOS + Android)
│ └── studio/ macOS SwiftUI app (not an npm workspace)
├── packages/
│ ├── core/ @gracechords/core — shared, DOM-free logic (ChordPro parser,
│ │ transposition, RBAC, setlist codec, Supabase factory)
│ └── tokens/ @gracechords/tokens — design tokens (web CSS + native TS map + generated Swift)
├── workers/ Cloudflare Workers (PPTX upload, sitemap rebuild, Telegram bot, session cleanup)
└── supabase/ SQL migrations (songs, users, posts, setlists, …)
| Workspace | Package | What it is |
|---|
apps/web | @gracechords/web | The production single-page app: full song catalog, setlists, worship mode, admin/editor portals, Daily Word, posts. Deployed to Cloudflare Pages. |
apps/mobile | @gracechords/mobile | Native iOS and Android client (Expo SDK 55, Expo Router v7). A themed five-tab shell (Home · Songs · Setlists · Daily Word · Utilities) with a real chord-chart Song Viewer, Performer mode, the setlist builder (with import), a song editor, live sessions, the Daily Word landing + reader (M'Cheyne reading, devotionals, private journal reflections, an opt-in reading streak, offline Bible downloads), musician utilities (tuner, metronome, pitch pipe, songbook, capo, key reference), Setlist Stats, and native Google/Apple auth. |
apps/studio | — | Native macOS SwiftUI companion app for song creation and content management. Not an npm workspace; reuses packages/core through JavaScriptCore. |
packages/core | @gracechords/core | Pure TypeScript/JS shared by both apps — ChordPro parser (not the renderer), transposition, chord placement, song metadata/sort, the setlist codec, the role hierarchy, and the Supabase client factory. Consumed as source, no build step. |
packages/tokens | @gracechords/tokens | The single home for design tokens. Web imports tokens.css; native imports the typed map from @gracechords/tokens/native; apps/studio uses a committed Swift mirror generated from it (npm run tokens:swift). |
workers/* | — | Cloudflare Workers deployed independently: authenticated PPTX upload/delete, weekly sitemap rebuild, the @gracechords_bot Telegram bot, and live-session cleanup. |
Quick start
Use Node.js 20 LTS (20.19+, Vite 7's minimum). Install all workspaces from the repo root:
npm ci
Then run the app you want:
npm run dev # web dev server → http://localhost:5173
npm test # web test suite (Vitest)
npm run build # production web build → apps/web/dist/
The root package.json delegates these scripts to @gracechords/web. For the
full web setup (environment variables, Supabase, deployment) see
apps/web/README.md. For the mobile app (Expo, simulator,
env) see apps/mobile/README.md.
Infrastructure at a glance
| Service | Role |
|---|
| Supabase | Auth + Postgres — song catalog, users/roles, posts, starred songs, setlists, live sessions, reflections. Row-level security on every table. |
| Cloudflare Pages | Hosts the web SPA. Builds from the apps/web root directory to apps/web/dist/ on every push to main. |
| Cloudflare Pages Functions | Server-side code at apps/web/functions/: same-origin R2 proxies (bible/, pptx/) that avoid CORS, plus api/ endpoints (export, Telegram, bot, crash reports). |
Cloudflare R2 (gracechords-bible) | Stores PPTX slide decks (pptx/) and Bible chapter JSON (bible/). |
| Cloudflare Workers | gracechords-pptx-upload (authenticated PPTX writes), gracechords-sitemap-rebuild (weekly cron), gracechords-telegram-bot, gracechords-session-cleanup (15-min cron). |
| Cloudinary | Browser-side image hosting for song/post cover images. |
| Resend | Transactional email (server-side only). |
Full details live in the wiki's Cloudflare Infrastructure
page and in apps/web/AGENTS.md.
Roles & access
GraceChords uses four roles: user → editor → admin → owner.
The hierarchy is defined once in packages/core/src/rbac/roles.js and enforced
via hasMinRole(). See Roles & Access for the
permission matrix and the admin/editor portals.
Roadmap
Current focus and planned work:
- Tablet-responsive web layout — a proper master-detail experience on larger screens.
- Mobile app — the iOS and Android app ships through EAS Build (see
apps/mobile/RELEASING.md); next up is offline song/setlist persistence.
- GraceTracks integration — surface practice stem tracks (
has_stems / stem_slug / gracetracks_url) across web and mobile.
- Shared-core growth — migrate more query/util logic into
@gracechords/core as the mobile app needs it, keeping web and native in lockstep.
Contributing & conventions
License
Licensed under the terms in LICENSE. See NOTICE for
attribution.
