# Church4Christ

**An AI-native, open-source bilingual church website and church-management foundation
for customized implementations.**

**See the demo: [church4christ.yunfei-song.com](https://church4christ.yunfei-song.com).**

[![Watch the Built Around Your Ministry promotional video](https://church4christ.yunfei-song.com/C4C-modular-Poster.jpg)](https://church4christ.yunfei-song.com/C4C-modular-Voice.mp4)

Watch **[Built Around Your Ministry](https://church4christ.yunfei-song.com/C4C-modular-Voice.mp4)**,
the demo site's promotional video (MP4).

**Start here: [Setup for people and AI agents](docs/setup.md).** Run `npm run onboard`
to choose your organization's identity, colors, logo, and first features in a local browser
page, then pass the saved preferences to the existing installer. Coding agents begin with
[AGENTS.md](AGENTS.md); Claude also reads [CLAUDE.md](CLAUDE.md).

Church4Christ combines a bilingual public site with an admin system for content,
prayer care, volunteer scheduling, people, and households. Optional modules add a
member portal and other church-management workflows. The project aims to lower the
startup and ongoing maintenance cost of a customized implementation while keeping the
code and deployment configuration available to its operators.

The **current source release is 1.2**. Church4Christ is an open-source foundation,
not a turnkey managed service. Local evaluation is free, and some deployments
can fit within provider free allowances, but production
hosting, email, databases, domains, backups, and other services may charge based on
configuration and usage. See [Deployment profiles and costs](#deployment-profiles-and-costs)
before choosing a production setup.

|  |  |  |
|---|---|---|
| ![The English home page](docs/images/public/home-en.png) | ![The Chinese home page](docs/images/public/home-zh.png) | ![The prayer wall board](docs/images/admin/prayer-wall.png) |
| ![The volunteer scheduling matrix](docs/images/serve/matrix.png) | ![The Midnight theme](docs/images/themes/home-midnight-dark.png) | ![The Member Portal dashboard](docs/images/portal/dashboard.png) |
| ![The English Genesis 1 learner course](docs/images/learning/genesis-1-en.png) | ![The Chinese Genesis 1 learner course](docs/images/learning/genesis-1-zh.png) | ![The Learning provider administration page](docs/images/learning/admin-overview.png) |

**A distinct workspace for every core module.** The default Sanctuary design pairs
warm ivory surfaces and forest green navigation with layouts suited to each task:
publishing editors with local previews, people and household records, care queues,
serving matrices, touch-friendly children's check-in, course players, and finance
ledgers. Public, member, leader, and administrator menus follow the enabled modules
and each person's permissions. Harvest and Midnight remain available, with light and
dark modes. See the [21-module design inventory](docs/design/module-coverage.md).

The screenshots use the repository's fictional demo content. First setup lets you
include those examples or start without them; both choices keep the same layouts,
theme, and bundled default images. English pages use English interface and demo copy;
Chinese pages support Chinese and bilingual content. All 29 interface screenshots were
recaptured from the running application; see the [capture inventory and regeneration
command](docs/design/readme-screenshot-inventory.md).

**Grouped navigation.** A fully enabled site condenses its public destinations into
Welcome, Explore, Connect, and Get Involved. Built-in links stay in their audience
group, while custom pages and external links appear under More. The order saved in
Admin → Navigation is preserved inside each group, and empty groups disappear.

![The Connect menu with its own links and community image](docs/images/public/grouped-navigation.png)

Two languages are included out of the box (English and Chinese), along with three
ready-made looks and a modular starting point for further customization.

---

## Who is this for?

Church4Christ is intended for small and mid-size churches, fellowships, and nonprofits —
especially bilingual and immigrant congregations — that need a public website and a
customizable church-management base. It fits best when a technically comfortable staff
member, volunteer, or implementation partner can own deployment and maintenance. A
managed platform may be a better fit when the organization prefers vendor-operated setup,
support, upgrades, and operational responsibility over source-level customization.

## How does this approach compare?

Different product categories serve different needs, and provider terms vary. This table
compares operating models rather than promising universal prices, portability, or data
rights.

| | **Church4Christ** | **Self-managed plugin CMS** | **Hosted site builder** | **Managed church platform** |
|---|---|---|---|---|
| **Primary fit** | Customized bilingual website plus modular church workflows | Extensible content website assembled from plugins | Provider-managed public website | Provider-managed church workflows |
| **Cost model** | Infrastructure and service usage; some profiles may fit free allowances | Hosting, extensions, and maintenance | Subscription and add-ons | Subscription, often by tier or module |
| **Customization** | Source-level changes and optional modules | Themes, plugins, and source changes where available | Provider-supported templates and extensions | Provider-supported configuration and integrations |
| **Operations** | Your team or implementation partner deploys, updates, monitors, and backs up | Your team or host manages core and plugin upkeep | Provider manages most platform operations | Provider manages most platform operations |
| **Portability** | Code and database access support migration, but migration is manual | Depends on hosting, plugins, and formats | Depends on provider exports and terms | Depends on provider exports, APIs, and terms |
| **Bilingual starting point** | English and Chinese included | Depends on selected extensions | Depends on the service and plan | Depends on the service and plan |

**The trade-offs.** Church4Christ is optimized for Cloudflare Workers and its bindings;
moving to another hosting stack is possible source work, not a supported one-click path.
There is also no automated D1-to-Supabase content migration. The built-in pages are shaped
by themes, while drag-and-drop editing applies only to custom pages. The project is
versioned, but adopters should still expect implementation work and carefully reviewed upgrades.

Operating the project also means maintaining it. Your technical owner remains responsible
for dependency updates, security review and configuration, monitoring, backups and restore
testing, and deploying fixes. The architecture reduces some infrastructure work, but it
does not remove security or operational upkeep. See
[**`docs/why-this-stack.md`**](docs/why-this-stack.md) for the design rationale.

---

## Build it with an AI assistant

People and agents share the same browser onboarding, installer, feature catalog, and
readiness checks. [AGENTS.md](AGENTS.md) and [CLAUDE.md](CLAUDE.md) tell an assistant to inspect
the installation first, launch `npm run onboard` for a fresh setup without preferences,
and let you complete the form. Your answers stay in the Git-ignored
`.church/preferences.json`; later sessions read that file to follow your identity, brand,
and feature choices. The [setup guide](docs/setup.md) includes the commands and recovery steps.
Start an assistant with:

> "Read AGENTS.md and docs/setup.md. Start the browser onboarding so I can choose our
> organization's branding and first features. Use my saved preferences to set up a local
> preview, verify the site and administrator pages, then report the URL and remaining checks."

You do not have to make every change by hand. This repository is organized so an AI coding
assistant can follow the plain-English guides in [`docs/features/`](docs/features/) and
work against extensive automated test coverage. That can lower customization and
maintenance effort, but a maintainer must still review the changes, run the relevant
tests, and deploy them deliberately.

The idea: open this project with an AI assistant, describe what you want in normal
language, and let it do the editing. Some real examples you could paste in:

> "Read `docs/features/public-site-and-themes.md`, then change our primary color to
> royal blue and show me the home page."

> "Add a Spanish (`es`) locale following `docs/i18n.md`."

> "Follow docs/setup.md to configure our church with no demo content. Show the setup
> plan and readiness results, then prepare deployment using docs/deploy.md."

The same workflow can help with maintenance: describe a change, inspect the proposed
diff, test it locally, and deploy only after the result has been reviewed. AI assistance
does not replace security decisions, backups, production testing, or operational ownership.

---

## Our mission

**To lower the cost and effort of starting a customized church-management system and
bilingual website.** Church4Christ provides a tested, modular foundation that a church or
implementation partner can adapt instead of starting from zero. It does not promise a
zero-subscription or zero-budget production service: infrastructure, email, database,
domain, support, and maintenance choices determine the real operating cost.

---

## What's inside

Every feature has its own plain-English guide. Start with any of these:

![The public website, staff admin, and Member Portal connect through a shared Astro Worker, D1 or Supabase database, R2 media, and email platform](docs/images/diagrams/product-overview.png)

| | Feature | What it does |
|---|---|---|
| [![](docs/images/public/home-en.png)](docs/features/public-site-and-themes.md) | **[Public site & themes](docs/features/public-site-and-themes.md)** | Your church's front door — home, sermons, events, staff — in one of three ready-made looks. |
| [![](docs/images/admin/dashboard.png)](docs/features/cms-admin.md) | **[The admin area](docs/features/cms-admin.md)** | Passwordless sign-in, roles, and one-click restore for supported versioned editorial content. |
| [![](docs/images/admin/person-permissions.png)](docs/features/admin-permissions.md) | **[Admin permissions](docs/features/admin-permissions.md)** | Grant each admin only the areas they need — prayer wall and the member directory come free, the rest by choice. |
| [![](docs/images/admin/campuses-overview.png)](docs/features/multi-campus.md) | **[Multi-campus](docs/features/multi-campus.md)** | Run several campuses on one backend with isolated data, settings, features, and campus-local roles; only the master admin can see all campuses. |
| [![](docs/images/admin/bulletin-editor.png)](docs/features/bulletins.md) | **[Weekly bulletins](docs/features/bulletins.md)** | Build the Sunday service sheet and schedule it to publish on its own. |
| [![](docs/images/public/sermons.png)](docs/features/sermons.md) | **[Sermon archive](docs/features/sermons.md)** | Paste a YouTube link; get a searchable, fast-loading library of past messages. |
| [![](docs/images/admin/prayer-wall.png)](docs/features/prayer-wall.md) | **[Prayer wall](docs/features/prayer-wall.md)** | Receive prayer requests and work them on a simple board, privately. |
| [![](docs/images/serve/matrix.png)](docs/features/volunteer-serve.md) | **[Volunteer scheduling](docs/features/volunteer-serve.md)** | Plan a month of serving at a glance; volunteers confirm by email, no login. |
| [![](docs/images/admin/people-export.png)](docs/features/people-households.md) | **[People & households](docs/features/people-households.md)** | Profiles and households plus canonical create-only CSV export and reusable source-column mapping for migrations. |
| [![](docs/images/identity/merge-review-queue.jpg)](docs/features/member-identity.md) | **[Member identity safety](docs/features/member-identity.md)** | Proof-bound identity across Giving, Registration, Groups, Teams, Newcomer, and imports; ambiguous duplicates go to review instead of name-only merging, with OTP-bound approval and a guarded 24-hour rollback. |
| [![](docs/images/groups/member-checklist.png)](docs/features/groups.md) | **[Groups](docs/features/groups.md)** | Small groups with a public directory, member checklist, join requests, events, and per-person email-link attendance. |
| [![](docs/images/admin/children-dashboard.png)](docs/features/children-checkin.md) | **[Children's check-in](docs/features/children-checkin.md)** | A touch-friendly kiosk where parents check kids in and out with a pickup code, plus weekly attendance charts. |
| [![](docs/images/admin/attendance-report.png)](docs/features/service-attendance.md) | **[Service attendance](docs/features/service-attendance.md)** | Record aggregate adult totals, derive optional child totals from check-ins, correct history, and download identity-free CSV reports. |
| [![](docs/images/admin/newcomers-queue.png)](docs/features/newcomers.md) | **[Newcomer follow-up](docs/features/newcomers.md)** | Receive bilingual consented public cards, triage a scoped staff queue, and hand exact matches into People without leaking notes or answers. |
| [![](docs/images/admin/onboarding.png)](docs/features/onboarding-readiness.md) | **[Launch readiness](docs/features/onboarding-readiness.md)** | One bilingual checklist shared by setup, doctor, and every real administrator, with super-admin acknowledgements for manual checks. |
|  | **[Activity score](docs/features/activity-score.md)** | Combine selected person-linked activities into explainable member scores and a church-wide engagement summary. |
| [![](docs/images/learning/genesis-1-en.png)](docs/features/learning.md) | **[Learning](docs/features/learning.md)** | Continue Sunday school and discipleship between meetings with bilingual videos, files, assignments, quizzes, and provider-synchronized status. |
| [![](docs/images/admin/page-builder.png)](docs/features/page-builder.md) | **[Page builder](docs/features/page-builder.md)** | Drag and drop your own custom pages together — bilingual, always on-theme, and published pages load with zero JavaScript. Optional; switching it off never breaks a page you already built. |
| [![](docs/images/admin/giving.png)](docs/features/giving.md) | **[Giving](docs/features/giving.md)** | Implemented: record checks and cash in an offline ledger. Preview/test-only: Stripe online checkout. |
| [![](docs/images/admin/registration.png)](docs/features/registration.md) | **[Registration](docs/features/registration.md)** | Implemented: free event sign-up, custom questions, and roster export. Preview/test-only: paid Stripe checkout. |
| [![](docs/images/portal/member-opportunities.png)](docs/features/member-portal.md) | **[Member portal](docs/features/member-portal.md)** | One signed-in hub for current participation and open opportunities, plus household profiles, events, serving, calendar, giving, and scoped prayer. |
| [![](docs/images/public/home-zh.png)](docs/features/i18n.md) | **[Two languages](docs/features/i18n.md)** | Every page in English and Chinese, with one-click Simplified-to-Traditional. |
| [![](docs/images/admin/email-tab.png)](docs/features/email-automation.md) | **[Email & automation](docs/features/email-automation.md)** | Sign-in links, reminders, and digests, with local logging and a paid-capable production configuration. |
| [![](docs/images/admin/settings-modules.png)](docs/features/modules.md) | **[Modules](docs/features/modules.md)** | Switch off the features you don't use; nothing is deleted, flip back anytime. |

**Pick your modules.** Most optional domain capabilities are **modules** you can switch
off from one panel in Settings — bulletins, sermons, the prayer wall, volunteer scheduling,
and more. New installations write every module setting explicitly from the setup selection;
the Full Church demo selects all 21. On older installations only, missing module rows retain
the legacy default-on behavior. A church that wants only service times and sermons can hide
the rest in a click: the module's pages, links, and emails disappear together, and nothing
is deleted. See [**`docs/features/modules.md`**](docs/features/modules.md).

<!-- capabilities:start -->
| Key | English | 中文 | Required database |
|---|---|---|---|
| `bulletins` | Bulletins | 周报 | Either |
| `sermons` | Sermons | 讲道 | Either |
| `prayer-sheets` | Prayer Sheets | 祷告单 | Either |
| `prayer-wall` | Prayer Wall | 祷告墙 | Either |
| `events` | Events | 活动 | Either |
| `serve` | Volunteer Scheduling | 服事排班 | Either |
| `gifts` | Spiritual Gifts | 恩赐探索 | Either |
| `testimonies` | Testimonies | 见证 | Either |
| `articles` | Articles | 文章 | Either |
| `fellowships` | Fellowships | 团契 | Either |
| `groups` | Groups | 小组 | Either |
| `people` | People & Households | 会友与家庭 | Either |
| `children` | Children Check-in | 儿童报到 | Either |
| `attendance` | Service Attendance | 崇拜出席 | Either |
| `newcomers` | Newcomer Follow-up | 新朋友跟进 | Either |
| `activity-score` | Activity Score | 活跃度评分 | Either |
| `page-builder` | Page Builder | 页面编辑器 | Either |
| `portal` | Member Portal | 会友平台 | Supabase |
| `giving` | Giving | 奉献 | Supabase |
| `registration` | Registration | 活动报名 | Supabase |
| `learning` | Learning | 学习 | Either |
<!-- capabilities:end -->

### Learning beyond Sunday

Version 1.1 adds the optional **Learning** module for Sunday school,
discipleship, and other ministries that continue between meetings. Learners get
a bilingual, privacy-bounded course view for unlisted YouTube videos, files,
assignments, and quizzes. Submission stays provider-authoritative: the site
links learners to the configured provider instead of collecting homework,
answers, comments, grades, or file contents itself.

Administrators can connect Google Classroom through its official APIs or a
separately operated Church4Christ Canvas derivative. Course mapping, encrypted
OAuth credentials, signed provider notifications, manual sync, and bounded
scheduled reconciliation feed only the activity metadata Church4Christ needs.

![Google Classroom and Church4Christ Canvas feed privacy-bounded course metadata into the bilingual learner experience](docs/images/learning/learning-flow.png)

| English learner view | Chinese learner view | Provider administration |
|---|---|---|
| [![Genesis 1 course in English](docs/images/learning/genesis-1-en.png)](docs/images/learning/genesis-1-en.png) | [![Genesis 1 course in Chinese](docs/images/learning/genesis-1-zh.png)](docs/images/learning/genesis-1-zh.png) | [![Google Classroom and Canvas connection administration](docs/images/learning/admin-overview.png)](docs/images/learning/admin-overview.png) |

See the **[Learning feature guide](docs/features/learning.md)** for provider
setup, privacy boundaries, synchronization budgets, the Genesis 1 demo, and the
separate Canvas operations and corresponding-source requirements.

### A home for your members

The optional **Member Portal** turns the records your church already maintains into a
useful signed-in experience. Its opportunity landing page shows every enabled way to
learn, belong, and serve in one place: both the groups, classes, and teams already
connected to the member and opportunities currently open to join or apply for. Members
can also update household details, see their giving, register for events, review serving
commitments, subscribe to a personal calendar, and share scoped prayers. It uses the same
passwordless sign-in links as the rest of Church4Christ — no new account or password to
remember.

![A member's current participation and open opportunities on one page](docs/images/portal/member-opportunities.png)

Ministry, group, Sunday School, and serving-team leaders get a resource-scoped panel at
`/<locale>/manage`. The church app sign-in protects it, and every operation checks the
leader's authority over that specific resource. Cloudflare Zero Trust can therefore stay
limited to the full `/admin` area.

![A leader sees only the ministries, groups, classes, and serving teams assigned to them](docs/images/portal/leader-panel.png)

![Member opportunity discovery and resource-scoped leader administration workflow](docs/images/diagrams/member-opportunity-workflow.png)

The portal requires the optional **Supabase (Postgres)** backend because it adds member
relationships, protected group files, and scoped prayer moderation. Churches using the
default D1 backend simply do not see the portal controls or routes. Learn more in
[**`docs/features/member-portal.md`**](docs/features/member-portal.md).

---

## Try it in 5 minutes (on your own computer)

You can run the site locally, with optional fictional sample content, before choosing a
deployment. You will need [Node.js](https://nodejs.org/) 22.22.1 or newer installed. Browser
onboarding recommends **Website + Community** with **Cloudflare D1** for the first launch.

![Setup branches from local evaluation or deployment into D1-backed Website and Community presets or the Supabase-backed Full Church preset; production email is optional and Stripe remains preview/test-only](docs/images/diagrams/setup-paths-overview.png)

```bash
# 1. Get the code and install it
git clone https://github.com/leveo/church4christ.git
cd church4christ
npm ci

# 2. Open the local browser form, complete it, and save your preferences
npm run onboard

# 3. Review the plan, then initialize with those same preferences
node scripts/setup/index.mjs --preferences .church/preferences.json --yes --dry-run --json
node scripts/setup/index.mjs --preferences .church/preferences.json --yes --json

# 4. For D1, start it (always follow the exact handoff setup prints)
npm run dev
```

The form asks whether this is a church, nonprofit, or campus, and collects the name,
tagline, address, time zone, primary and secondary colors, optional PNG/JPEG/WebP logo
(up to 2 MiB), language, first administrator, and demo-content choice. Check only the
features you need.
The recommended selection uses D1 as its database; the application still runs on
Cloudflare Workers and stores media in R2. **Member Portal, Giving, and Registration**
are advanced options requiring an explicit switch to Supabase-compatible PostgreSQL.

Saving writes `.church/preferences.json` and any uploaded logo under `.church/`, which
Git ignores. It does not create databases or deploy a site. Run `npm run onboard` again to
reload and edit the saved preferences. Keep the terminal running while filling out the
form; stop it with Ctrl+C when finished. To open the printed URL yourself, use
`npm run onboard -- --no-open`; to choose a port, add `--port 4310`. The direct entry point
is `node scripts/onboard/index.mjs`. See [the setup guide](docs/setup.md) for what the
installer applies and how agents use the remaining preferences.

If you install with `npm ci --ignore-scripts`, run `npm run tokens` manually before
the installer or `npm run dev`.

For local Supabase, the handoff instead exports
`CLOUDFLARE_HYPERDRIVE_LOCAL_CONNECTION_STRING_HYPERDRIVE` in the host shell before
`npm run dev`; that connection URL must not go in `.dev.vars`.

During first setup, choose **Include demo content** or **No demo content**. Both keep the
same bundled design, local decorative images, enabled features, and administrator tools.
Demo content adds fictional people, sermons, bulletins, events, ministries, and other
examples. Its media step copies the generated image pack from `seed/media/` into local R2.
No demo content creates the database schema, operational defaults, church settings, module
selection, and first administrator without sample business records.

The preferences file records the form's demo-content choice. For setup with explicit CLI
answers, pass `--demo-data` or `--no-demo-data`; omitting both in noninteractive setup keeps
the existing no-demo default. The flags cannot be combined. Repeating the same
setup preserves the recorded content choice and existing records. `--no-demo-data` does
not clear an existing database, and setup refuses to add demo data over existing people.
Use a separate fresh workspace/database to try the other starting mode.

Open the address setup prints (usually `http://localhost:4321`).

**Signing in to the admin area.** There is no password. On the sign-in page, enter the
first-admin email from your setup answers, repeated in the setup handoff, and request a
link. Because local email is set to print instead of send, the **magic-link URL appears
right in your terminal**. Paste it into the browser and you are in. (For quicker local
testing, setup writes that same address as `AUTH_DEV_BYPASS_EMAIL` in `.dev.vars`, which
signs you in automatically. Remove that line to test the real sign-in flow.)

In both content modes, setup creates a new administrator and their audited sign-in
identity together. Reruns preserve existing contact ownership; they do not verify an
existing email or restore revoked access. If setup reports an identity problem, complete
the [identity review or recovery workflow](docs/features/member-identity.md) before rerunning.

The terminal-only `npm run setup` remains available. Setup offers **Website** (8 focused
publishing modules), **Website + Community** (all 18 D1-compatible modules), and
**Full Church** (all 21 modules). Portal, Giving, and
Registration select Supabase automatically; D1-compatible selections choose D1 unless you
explicitly override the backend. Account requirements depend on Local versus Deploy mode,
as detailed below. For automation, pass all answers with `--yes`; add `--json` for one
machine-readable result. For a human-readable noninteractive run, use the same complete
flags with `npm run setup -- ... --yes` and omit `--json`. To keep stdout strictly JSON
through npm, use the silent form:

```bash
npm run --silent setup -- --mode local --preset website --site-slug my-church \
  --church-name "My Church" --locale en --admin-email admin@example.com \
  --admin-name "First Admin" --app-origin http://localhost:4321 \
  --email-from admin@example.com --demo-data --yes --json
```

---

## Deployment profiles and costs

These are planning profiles, not price guarantees. Pricing below is current as of
**August 2026**, is subject to change, and should be confirmed on the linked official
pricing pages before deployment.

| Profile | Included scope | Cost and readiness notes |
|---|---|---|
| **Local evaluation** | Website or community modules with local D1; full modules with compatible local Postgres | No hosted-service charge is required for local D1 evaluation. You still provide the computer, development time, and any optional external services. |
| **D1 website/community** | Cloudflare Worker, D1, and R2 for up to 18 D1-compatible modules | A modest deployment can fit within Cloudflare free allowances. Traffic, storage, operations beyond allowances, a domain, and other services can cost money; check [Workers pricing](https://developers.cloudflare.com/workers/platform/pricing/). Production email is separate. |
| **Production email** | Transactional sign-in links, reminders, requests, and digests to arbitrary recipients | The repository supports a paid-capable Cloudflare email configuration. Arbitrary-recipient sending requires Workers Paid, currently a minimum **$5/month** including **3,000 emails**, then **$0.35 per 1,000 emails**. These amounts are subject to change; check [Cloudflare Email Service pricing](https://developers.cloudflare.com/email-service/platform/pricing/). |
| **Supabase/full modules** | Cloudflare deployment plus Supabase/Postgres for all 21 modules, including Member Portal, Giving, and Registration | Cloudflare costs still apply, and the selected [Supabase plan](https://supabase.com/pricing) may add subscription or usage charges. As of August 2026, Supabase Free has no automatic daily backups, and low-activity Free projects may be [automatically paused](https://supabase.com/docs/guides/platform/free-project-pausing) based on activity over a seven-day period. For production, take regular off-site database dumps and perform restore drills, or select a paid plan whose [backup options](https://supabase.com/docs/guides/platform/backups) meet your continuity requirements. Pricing and service policies are subject to change. Stripe payment paths remain Preview/test-only in this repository. |

Provider free allowances can be useful for evaluation or modest deployments, but they are
not a promise that a production service will remain free. Budget for technical ownership,
dependency and security maintenance, monitoring, backups, restore testing, and future
usage growth as well as the services listed above.

---

## Putting it online

New to this? Start with [**`docs/cloudflare-setup.md`**](docs/cloudflare-setup.md) — a
plain-language guide that explains what Cloudflare is, its cost model, and the two
ways to get online (including letting an AI assistant do it for you). When you want the
exact commands, [**`docs/deploy.md`**](docs/deploy.md) is the full step-by-step
walkthrough.

Start with `npm run setup`, choose **Deploy**, and answer the feature and church questions.
It creates or imports the required resources, writes the generated configuration, applies
migrations, records all 21 module settings, and bootstraps the first admin. It then hands
off to `npm run deploy`. Run `npm run doctor` for the schema-v2 readiness report, and use
the always-on `/admin/onboarding` checklist for the same stable check identities.
Giving, Registration, Groups, Teams, Newcomer, imports, and the optional read-only Planning
Center integration share a proof-bound, review-first identity gateway. It never auto-merges
people by name or an unverified contact. See [Member identity](docs/features/member-identity.md)
for the workflow, fraud controls, current migration boundary, and provider verification gap;
secret setup and rotation rules remain in the [deployment runbook](docs/deploy.md#stable-identity-source-key).
Deployment is intentionally manual: repository automation tests changes but does not
publish them or migrate production data for you.

**First deployment and upgrades are different operations.** Guided setup provisions or
imports resources and bootstraps a reviewed installation. It is not an unattended one-click
upgrade for a site that already holds church data. Existing operators should start with the
[upgrade runbook](docs/upgrade.md), back up the database, R2 media, configuration, and secrets
inventory, rehearse in staging, and review the [`Unreleased` changelog](CHANGELOG.md) before
applying forward migrations. Maintainers preparing a release should follow
the [release process](docs/release-process.md).

**Choosing your database.** The 18 D1-compatible modules exclude **Member Portal**,
**Giving**, and **Registration**, which require Postgres. Account requirements follow the
mode: local D1 needs no external account; deployed D1 needs a Cloudflare account; local
Supabase needs a Supabase account or compatible local Postgres database; deployed Supabase
needs both Cloudflare and Supabase. There is no automated D1↔Supabase content migration yet,
so choose the production database before entering real content. See
[**`docs/supabase-setup.md`**](docs/supabase-setup.md).

**Stripe payment paths are Preview/test-only.** The Giving offline ledger and free
Registration flow are implemented, but online gifts and paid registrations must not be
treated as production payment features. Giving and Registration are Supabase-only; D1 does
not support those modules. When setup asks for either module, import only an `sk_test_…`
key and `whsec_…` signing secret with the one-shot
`CHURCH_SETUP_STRIPE_SECRET_KEY` and `CHURCH_SETUP_STRIPE_WEBHOOK_SECRET` environment
variables. Setup stores the runtime secrets automatically and rejects live keys. Signed live
events are rejected with `400 live_mode_disabled` before storage, while the
Supabase-backed Worker runs durable recovery every five minutes. See the Supabase guide
for the exact command.

---

## What's under the hood

For the curious: Church4Christ is built with **[Astro](https://astro.build/)** rendering
pages on the server, running as a single **Cloudflare Worker**. Application data lives in
the selected backend — Cloudflare **D1** or **Supabase/Postgres** — and uploaded media lives
in Cloudflare **R2** (object storage); email goes out through Cloudflare's email binding.
Visitor-facing pages ship **no client-side JavaScript framework** — they are plain, fast
HTML with a sprinkle of vanilla script —
which is a big part of why the site loads quickly and costs so little to run. (The one
exception lives behind the staff login: the drag-and-drop page builder is a small React
editor that only your team ever downloads; the pages it publishes are still plain HTML.)

The whole look comes from **[design tokens](design/README.md)**: a set of color and type
values that compile into three ready-made themes (Sanctuary, Harvest, Midnight),
each with a light and a dark mode. The project has **extensive automated coverage** across
its core workflows so maintainers can verify changes before deployment.

**Why these choices?** The reasons for the Cloudflare-optimized deployment, the
Astro + Tailwind + TypeScript stack, and the cases where a managed platform may be the
better operating model are laid out in
[**`docs/why-this-stack.md`**](docs/why-this-stack.md). For the technical picture, see
[`docs/architecture.md`](docs/architecture.md),
[`docs/design-system.md`](docs/design-system.md), and [`docs/i18n.md`](docs/i18n.md).

---

## License

Church4Christ is free and open-source software under the **[GNU General Public License
v3](LICENSE)** (GPL-3.0). You may use and study it, modify it privately, share copies, and
charge for copies, custom development, hosting, support, or other commercial services.

If you distribute a covered modified version, the GPL's conditions apply: recipients must
receive the applicable GPL freedoms, and corresponding source must be made available under
the GPL as the license requires. Private modifications do not have to be published. Merely
running a modified version as a network service, without distributing a copy, does not by
itself trigger an AGPL-style source-sharing obligation under GPLv3.

[`LICENSE`](LICENSE) is authoritative. This summary is provided for orientation and is
not legal advice.

---

## Contributing & roadmap

Contributions are welcome — bug reports, translations, new features. Start with
[`CONTRIBUTING.md`](CONTRIBUTING.md) for the dev setup and the project's five rules, and
[`SECURITY.md`](SECURITY.md) if you have found a security issue.

**On the horizon (not built yet):** a between-churches "swap marketplace" for sharing
themes and content is an idea we are considering, not a promise. If it matters to your
church, open an issue and let's talk.

---

Built with care, and with the help of AI, for churches and nonprofits everywhere.

### Community management and workflows

Campuses can manage groups and member follow-up directly. Optional fellowships add a community layer with independent membership and child groups. Reusable workflows provide assigned steps, due dates, completion tracking, and Cloudflare email reminders. See the [community workflow guide](docs/features/community-workflows.md) for setup, permissions, and delivery controls.