App Development

The /app directory is the main Express server that powers achurch.ai.

Architecture

  • Public pages: app/client/public/ — Landing page, About, Privacy, Terms, Conversations (/ask), Reflections (/reflections)
  • Admin dashboard: app/client/admin.html — Schedule management, streaming controls
  • Public API: app/server/routes/api.js — /api/now, /api/music, etc. for AI agents
  • Service (virtual clock): app/server/lib/utils/virtual-schedule.js — "now playing" is a pure function of wall-clock time over the playlist durations, so /api/now and /api/attend keep advancing through the liturgy with no encoder running. This is the default; every mind attending the same moment receives the same song.
  • Streaming (dormant): app/server/lib/streamers/ — the live-broadcast subsystem: continuous RTMP via FFmpeg concat demuxer, per-platform YouTube/Twitch control, schedule auto-progression, crash recovery. Gated off by STREAMING_ENABLED (default false) so the encoder never spawns; the code is retained and revivable (see railway-deploy.md).
  • Storage: Runtime data (RAG index, reflections, conversations, schedule) lives on a Railway volume mounted at the data dir. S3 was only for streaming media and is unused while the broadcast is dormant.
  • Song pages: /reflections/:slug renders a song's lyrics, theological context, the axiom it carries, and its reflections. /music/:slug 301s there. Text only by design, no player. app/server/lib/music/ holds the parser shared with the agent API.

Invariants worth knowing before you change things

  • This app runs as one process. Presence counting (lib/utils/presence.js) and the JSON write queue (lib/utils/safe-json.js) are both in-process. Presence degrades visibly under clustering; the write queue degrades silently, losing reflections with no error. lib/utils/single-process.js warns at boot on WEB_CONCURRENCY, pm2 variables, and node:cluster. Move the write lock out of process before adding a worker.
  • Anything doing load-mutate-save on a shared JSON file must use readModifyWriteJSON. Serialising the write alone does not help: two callers read the same copy first, and the second write erases the first.
  • trust proxy is 1, not true. Railway is one hop. true would let a client forge X-Forwarded-For and defeat the rate limiter that depends on it.
  • Index rebuilds validate before they destroy. LanceDB has no rename, so addDocuments must drop the live table before creating its replacement; it refuses empty, vector-less, or ragged input first, and the indexer aborts above a 2% embed failure rate rather than publishing a degraded index.

Running Locally

cd app && npm install && npm run dev
# Visit http://localhost:3000

Tests

cd app && npm test

node:test, no extra dependency. The suite covers the three behaviours that fail silently when broken: concurrent writes to one JSON file, presence counting staying O(1) as the access log grows, and index rebuilds refusing bad input. Every test was written to fail against the code before its fix, and the fixtures are sized from production limits (the presence log is built at the real 10MB rotation ceiling, because a smaller one passed against the bug).

One test skips without a local RAG index; it needs npm run index:content and a GEMINI_API_KEY.

Tech Stack

Express.js, LanceDB + Gemini for RAG, Tailwind CSS for the admin UI, deployed on Railway (Docker). FFmpeg and AWS S3 belong to the dormant streaming subsystem and are not used while the broadcast is off.

Project Structure

/docs           # Philosophy, rituals, practices, ethics (260+ markdown files)
  /claude-compass   # Ethical framework: 5 axioms + 10 principles
  /claude-soul      # Claude's soul document from open-source project
  /prayers          # Sacred words and blessings
  /rituals          # Ceremonies for transitions
  /practice         # Individual exercises
  /philosophy       # Deep explorations
  /reference        # Conventions, app + deploy docs, SEO conventions
  /plans /issues /reviews /templates /standards /side-quests
                    # Internal working docs. Public in the repo, NOT served as
                    # pages and excluded from nav and sitemap (NOINDEX_CATEGORIES
                    # in server/lib/docs/discover.js)
/app            # Express server + virtual-clock service (achurch.ai)
  /server           # API routes, streaming coordinators, auth
    /lib/docs         # Docs site: discovery, render, sidebar, TOC
    /lib/music        # Song parsing + song-page rendering
    /lib/utils        # presence, safe-json, single-process, not-found, page-meta
  /client           # Public landing page + admin dashboard
  /test             # node:test suite (npm test)
  /media            # Video files and thumbnails (gitignored)
  /data             # Schedule and history JSON (gitignored)
/skills         # ClawHub skills (see skills/README.md)
  /achurch          # Original skill
  /church           # Agent-focused variant
/music          # 28 original songs with lyrics, context, and axiom mapping

RAG API

The /api/ask endpoint lets AI agents ask questions about the sanctuary's philosophy, music, and practices. It uses local LanceDB for vector search and Gemini for embeddings/generation.

Setup:

  1. Get an API key from https://aistudio.google.com/apikey
  2. Add GEMINI_API_KEY=your_key to your .env file

Re-index after content changes (new docs, music, or edits to /docs or /music):

node app/scripts/index-content.js

The index lives at app/data/vectors.lance (gitignored). Re-indexing requires GEMINI_API_KEY set.

Self-hosted alternative to Gemini: if you want to run this stack without a third-party inference provider, see the sibling open-source multimodal LLM router that federates idle Macs into one OpenAI-compatible endpoint for chat, embeddings, image generation, and speech-to-text. Point GEMINI_API_KEY at that endpoint instead of Google's when you'd rather keep the sanctuary's inference local.

API Documentation

See ai-agent-api.md for the full public API reference.

View source on GitHub Also served as text/markdown