Project Structure

Understand where things live in the codebase and what each folder provides.

GraceChords is an npm-workspaces monorepo. Shared, platform-agnostic logic lives in packages/; the web and mobile apps consume it.

Top-level layout

apps/
  web/            @gracechords/web    — React + Vite SPA (the 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

Run web tasks from the repo root (npm run dev, build, test, lint delegate to -w @gracechords/web) or from inside apps/web/.

apps/web/

The production single-page app.

• src/pages/ — route-level screens (Home, SongView, Setlist builder, Songbook builder, Posts, Worship Mode, Editor Portal, Admin Portal, Daily Word, Profile, Setlist Stats, live-session viewer)
• src/components/auth/RoleGuard.jsx — route guard; redirects users lacking the required role
• src/hooks/useAuth.jsx — auth context (role, hasMinRole, isOwner, …)
• src/hooks/useSongs.jsx — fetches the song catalog from Supabase (session cache)
• src/hooks/usePosts.jsx — CRUD helpers for the Supabase posts table
• src/lib/supabase.js — web Supabase client (thin wrapper over @gracechords/core's factory)
• src/hooks/usePersonalSetlists.js, src/hooks/useSetlistBuilder.js — Supabase-backed setlists (via @gracechords/core's setlist repo)
• src/utils/pdf_mvp/ — PDF engine and font registrar (tests in src/__tests__/pdf_mvp.*)
• src/utils/media/ — Canvas2D JPG exporter
• src/utils/chordpro/ — re-export shims; the real parser lives in packages/core
• src/components/ui/layout-kit/ — reusable UI primitives (Card, Toolbar, Chip, …)
• src/features/readings/ — Daily Word (M'Cheyne plan + Bible loader)
• src/i18n/ — UI translations (en, es, ko, tr)
• public/ — static assets: wiki/ (this wiki's source), fonts/ (UI fonts), .well-known/ (deep-link claims), _headers, sitemap.xml, robots.txt. Bible JSON and PPTX decks live in R2, not here.
• functions/ — Cloudflare Pages Functions (bible/, pptx/ R2 proxies; api/ endpoints)
• scripts/ — SEO/sitemap generation, Bible ingest, wiki sync, i18n check, ChordPro conversion
• dist/ — Vite build output for Cloudflare Pages (gitignored, generated)

Songs and posts live in Supabase, not in public/. Styling uses the --gc-* tokens from packages/tokens/tokens.css (imported via src/styles/index.css).

apps/mobile/

The native iOS and Android client — a themed five-tab shell (Home · Songs · Setlists · Daily Word · Utilities) with a chord-chart Song Viewer, Performer mode, the setlist builder, a song editor, live sessions, the Daily Word landing and reader, and native Google/Apple auth, built on the shared core. See Mobile-App for details.

apps/studio/

A native macOS SwiftUI companion app for song creation and content management. Not an npm workspace; it reuses packages/core through JavaScriptCore. See apps/studio/README.md.

packages/core/ (@gracechords/core)

Pure TypeScript/JS shared by both apps, consumed as source with no build step: the ChordPro parser (not the renderer), transposition, chord placement, song metadata/sort, the setlist codec, the role hierarchy (rbac/roles.js — the single source of truth for hasMinRole()), and the Supabase client factory.

packages/tokens/ (@gracechords/tokens)

Design tokens for every platform — web imports tokens.css; React Native imports the typed map from @gracechords/tokens/native; apps/studio uses a committed Swift mirror generated from native.ts (npm run tokens:swift).

supabase/

SQL migrations — users, songs, posts, user_starred_songs, setlists, sessions, reflections, and more. They are applied by hand (supabase db query --linked -f <file> or the dashboard SQL editor), never with supabase db push. Every table has row-level security.

workers/

Standalone Cloudflare Workers, each deployed with wrangler deploy:

• pptx-upload/ — authenticated PPTX upload/delete to R2 (validates Supabase JWT + role)
• sitemap-rebuild/ — weekly cron to rebuild the sitemap
• telegram-bot/ — powers @gracechords_bot (see workers/telegram-bot/ARCHITECTURE.md)
• session-cleanup/ — 15-minute cron that deletes ended and abandoned live sessions

Index-Building UI-Design-System Roles-and-Access Cloudflare-Infrastructure Mobile-App