Kidspire

A self-hostable children's ministry portal built as a Rails Engine gem. Family profiles, children management, event registration, and Planning Center sync — all in a single deployable package.

Part of the 5stones Software suite. MIT licensed. No dependency on any hosted platform.

---

Part of the 5stones suite

Repo	What it is
kidspire (this repo)	Kids ministry portal. Standalone. Self-hostable. MIT.
churchcred	Standalone points/badges gem. Self-hostable. MIT. Works alongside Kidspire.
More coming	Youthspire, Seniorspire — built on the same Inspire framework

Built by 5stones Software — open source tools churches can actually own.

---

What It Does

• Family profiles — parents create accounts, add children, manage contact info
• Children management — name, birthdate, grade, allergies/notes per child
• Event registration — public event listings with per-child signup forms
• Planning Center sync — connect your PCO account; family and child records sync automatically
• Passwordless auth — email magic link via Rodauth — no password required

---

Stack

Layer	Technology
Backend	Ruby on Rails (API + Engine)
Frontend	React + Vite + TypeScript
Styling	Tailwind CSS + shadcn/ui
Auth	Rodauth (passwordless email magic link)
Database	PostgreSQL
Background jobs	Sidekiq + Redis
Deployment	Railway (Procfile + railway.toml included)

---

Quick Start (Railway)

The fastest path is one-click Railway deploy:

1. Click Deploy on Railway above
2. Fill in the required environment variables in the Railway template form
3. Railway provisions PostgreSQL, Redis, and both services automatically
4. Once deployed, open a Railway shell and grant admin to your account:

   railway run bundle exec rails console
   # then: Account.find_by(email: 'you@yourchurch.org').update!(admin: true)

Local setup

Prerequisites: PostgreSQL, Redis, Node.js, and overmind running locally.

git clone https://github.com/5stones-io/kidspire
cd kidspire
cp .env.example .env

Edit .env and set at minimum:

• DATABASE_URL — replace your_pg_username with your local Postgres username (whoami on Mac/Linux)
• SECRET_KEY_BASE — generate with openssl rand -hex 64
• ENCRYPTION_KEY — generate with openssl rand -hex 32

bundle install
bun install
npx playwright install chromium  # for UI testing
bundle exec rails db:create db:migrate db:seed
overmind start -f Procfile.dev  # Rails :3000, Vite :3036, Sidekiq

---

Using as a gem (mountable engine)

Add to your Gemfile:

gem 'kidspire'

Mount in config/routes.rb:

mount Kidspire::Engine => '/'

Run the engine migrations:

bundle exec rails kidspire:install:migrations
bundle exec rails db:migrate

Configure in an initializer:

# config/initializers/kidspire.rb
Kidspire.configure do |config|
  config.pco_client_id     = ENV['PCO_CLIENT_ID']      # optional
  config.pco_client_secret = ENV['PCO_CLIENT_SECRET']  # optional
  config.pco_redirect_uri  = ENV['PCO_REDIRECT_URI']   # optional
  config.encryption_key    = ENV['ENCRYPTION_KEY']
  config.frontend_base_url = ENV['FRONTEND_BASE_URL']
end

---

Environment Variables

Required

Variable	Description
DATABASE_URL	Postgres connection string. Auto-set by Railway PostgreSQL plugin.
REDIS_URL	Redis connection string. Auto-set by Railway Redis plugin.
SECRET_KEY_BASE	Rails secret key. Generate: openssl rand -hex 64
ENCRYPTION_KEY	32-byte hex key for encrypting PCO tokens. Generate: openssl rand -hex 32
FRONTEND_BASE_URL	Public URL of your deployment. e.g. https://your-app.up.railway.app
VITE_API_BASE_URL	API base URL baked into the frontend at build time. e.g. https://your-app.up.railway.app/api/v1

Email (required for magic link auth)

Variable	Description
SMTP_ADDRESS	SMTP host. e.g. smtp.resend.com (Resend recommended — free tier)
SMTP_PORT	SMTP port. 465 for Resend.
SMTP_USERNAME	SMTP username. resend for Resend.
SMTP_PASSWORD	SMTP password / API key.
SMTP_DOMAIN	Your verified sending domain.
MAILER_FROM	From address. e.g. noreply@yourchurch.org

Optional

Variable	Description
PCO_CLIENT_ID	Planning Center OAuth client ID. Required for PCO sync.
PCO_CLIENT_SECRET	Planning Center OAuth client secret. Required for PCO sync.
PCO_REDIRECT_URI	e.g. https://your-app.up.railway.app/auth/pco/callback
PCO_KIDS_MINISTRY_TAG	PCO tag name to filter events. Defaults to pulling all events.
TWILIO_ACCOUNT_SID	Twilio SID for SMS invite links.
TWILIO_AUTH_TOKEN	Twilio auth token.
TWILIO_FROM_NUMBER	Twilio phone number.
CORS_ORIGINS	Allowed CORS origins. Defaults to FRONTEND_BASE_URL.
RAILS_LOG_LEVEL	Defaults to info.
DEBUG_PCO_SYNC	Set true for verbose PCO sync logs.

---

Planning Center Setup

Step 1 — Create a PCO OAuth app

1. Go to api.planningcenteronline.com/oauth/applications
2. Click New Application
3. Set redirect URIs:

   https://your-app.up.railway.app/auth/pco/callback
   https://your-app.up.railway.app/auth/pco/login/callback
   

4. Select scopes: people, check_ins, services
5. Copy the Client ID and Client Secret

Step 2 — Enter credentials in Kidspire

1. Log in as admin
2. Navigate to PCO Sync → PCO API Configuration
3. Paste Client ID and Client Secret → Save

Step 3 — Authorize

Click Connect PCO — approve the PCO consent screen. Kidspire stores your access and refresh tokens automatically.

---

Services

Service	Command
web	bundle exec rails db:migrate && bundle exec puma -C config/puma.rb
worker	bundle exec sidekiq

Railway worker service setup

Railway runs one process per service. Sidekiq needs its own service:

1. In your Railway project, click + New → GitHub Repo → select this same repo
2. Name it worker
3. Override Start Command to: bundle exec sidekiq
4. Override Build Command to: bundle install
5. Share the same DATABASE_URL and REDIS_URL environment variables from the PostgreSQL and Redis plugins

Without the worker service, background PCO sync jobs will not run. The web app still functions — sync must be triggered manually via the admin panel.

---

Allowed Hosts

Configure in config/environments/production.rb:

config.hosts = [
  "your-app.up.railway.app",
  "your-custom-domain.com"
]

---

Health Check

Rails default /up endpoint. Railway health checks hit this automatically.

---

Relationship to churchcred

Kidspire and churchcred are designed to run alongside each other. Kidspire handles family identity and event management. churchcred handles points, badges, and check-in rewards. They share the same PCO connection and the same family/child data model.

To run both:

# Gemfile
gem 'kidspire'
gem 'churchcred'

# config/routes.rb
mount Kidspire::Engine   => '/'
mount Churchcred::Engine => '/churchcred'

---

Versioning

Kidspire follows Semantic Versioning. See CHANGELOG.md for the full release history.

Bump	When
MAJOR	Breaking API, mount interface, or schema changes requiring manual intervention
MINOR	New features or endpoints (backwards compatible)
PATCH	Bug fixes, security patches, dependency updates

Pre-1.0 (0.x.y): minor bumps may include breaking changes while the API stabilises.

---

Releasing a new version

Uses gem-release to bump, tag, and push in one step.

1. Update CHANGELOG.md — move entries from [Unreleased] into a new versioned section and update the diff links at the bottom.

2. Bump the version and release:

# Patch release (0.1.0 → 0.1.1) — bug fixes only
gem bump --version patch --tag --push && gem release

# Minor release (0.1.0 → 0.2.0) — new features
gem bump --version minor --tag --push && gem release

# Major release (0.1.0 → 1.0.0) — breaking changes
gem bump --version major --tag --push && gem release

This will:

• Update lib/kidspire/version.rb
• Commit and tag v0.x.y
• Push the commit and tag to GitHub
• Build and push the gem to RubyGems

3. Create a GitHub release — go to github.com/5stones-io/kidspire/releases and publish release notes from the CHANGELOG entry.

---

Contributing

Open issues before large PRs. See 5stones.io for the broader suite roadmap.

---

License

MIT — see LICENSE

Built by

5stones Software · Open source tools for the local church