System Architecture

Seven layers from author intent to website presence

The Architecture at a Glance

JubileeArtifacts operates on a principle: the Markdown file in Git is the source of truth. Everything else — the database, the API, the website — is downstream. This guarantees that content is never lost, always recoverable, and fully auditable through Git history.

Seven layers transform author intent into visible content:

1

Authors

Writers create .md files locally or through collaborative editing pipelines. Each file contains YAML front matter (metadata) and GFM body (content).

↓
2

Markdown Files

Artifacts live in the canonical artifacts/ directory. This directory is the source of truth. One file = one artifact. Structure mirrors navigation.

↓
3

Git Repository

Every change is a commit. Full history is preserved. Rollback, blame, diff — all standard Git operations work on content.

↓
4

Sync Engine

A long-running service watches the Git working tree. On file change or Git event, it parses front matter and upserts the database. Latency: 5–10 seconds typical.

↓
5

PostgreSQL Database

Indexed, queryable. Contains artifacts, tree_nodes, relationships, tree_overrides tables. Can be rebuilt from Git at any time.

↓
6

API Layer

REST API serves read endpoints: /artifacts, /tree, /content. Narrow organizational write endpoints: /collections, /overrides. Gated by Jubilee Inspire SSO.

↓
7

Web UI

Renders tree navigation, artifact views, dashboards. Read-only for content. Can curate collections and tree overrides. All authenticated paths require SSO.

Key Invariants

1. Markdown is Source of Truth

The .md file in Git is always authoritative. Database is always downstream. Database can be deleted; git sync rebuilds it perfectly.

2. Web Does Not Author

The web UI cannot edit source artifacts. All editing happens in Markdown files. Authors use Git or collaborative tools — not the browser.

3. Database is an Index

The database is a queryable cache of the Git working tree. Its only purpose is to make searches and navigation fast. It is not a store.

4. Git is the History

Every change is a commit. git log shows who changed what, when, and why. There is no secondary audit log.

5. SSO is the Only Door

All authenticated features are gated by Jubilee Inspire Single Sign-On. No secondary auth, no backdoor, no API keys.

6. Structure Mirrors Everywhere

File structure, Git paths, database hierarchy, and website navigation all reflect the same logical structure. One mental model, four representations.

Data Flow: New Artifact Example

Sarah, a worship pastor, writes a new sermon:

  1. Writes locally: Creates artifacts/sermons/2026/mountains-moved.md with front matter and content.
  2. Commits to Git: git commit -m 'feat(sermon): Mountains Moved study in Matthew 17'
  3. Sync engine detects: Git post-receive hook triggers. Sync engine reads the file.
  4. Parses & upserts: Extracts title, author, date, tags from front matter. Creates/updates artifacts row. Creates tree_node for navigation.
  5. Search indexing: Content is indexed. Available in tree within 10 seconds.
  6. Web UI renders: Visitor navigates tree, finds "Mountains Moved," clicks, sees full sermon with metadata.
  7. Cross-platform consume: JubileeInspire API queries the artifact; Melody persona teaches from it. JSV Bible Society links to it. FiveFoldTest references it.

At every step, the single source of truth is the .md file. No step modifies Git. No step loses data. All steps are auditable.

Deployment Model

JubileeArtifacts runs on a single Nginx server. Three processes:

  • Web server: Nginx serving static HTML + reverse proxy to API
  • API server: Node.js running REST endpoints, gated by SSO
  • Sync engine: Node.js long-running service, watching Git and syncing database

All three connect to a shared Postgres instance. The sync engine has write access; the API and web servers have read-only access (enforced at the database role level).

Scalability & Resilience

This architecture scales simply:

  • Horizontal API scaling: Add more API servers; all read the same Postgres.
  • Sync engine is single-threaded: Only one sync engine per repo to prevent race conditions. If it fails, Git is still the source of truth.
  • Database backup: Standard Postgres backups. Recovery is simply point-in-time restore + `git sync` to re-verify.
  • Disaster recovery: If everything burns, recover from Git: clone the repo, restore database from backup, start sync engine. Full recovery in under 5 minutes.

Learn More

Sync Engine DocumentationFront Matter SchemaAPI ReferenceDay One Walkthrough