Technical Reference

System Architecture

Designed for speed without sacrificing truth. Understand how we sync MongoDB and GitHub in real-time.

Data Topology

👤User

Next.js App

MongoDB (Hot Cache)

GitHub API (Source)

Optimistic bidirectional synchronization

MongoDB Cache

Stores an indexed copy of your parsed files. Enables instant search, advanced filtering, and drafts that aren't yet commits. It is ephemeral: it can be rebuilt from scratch if deleted.

GitHub Source

The single source of truth. A post doesn't truly exist until it's committed to your `main` branch. The CMS always respects the Git history.

Concurrency Management

What happens if two people edit the same file? We use optimistic locking based on SHAs.

1. When reading a file, the CMS saves its blob_sha.
2. When saving, we send the new content along with the known last_sha.
3. GitHub's API rejects the commit if the remote SHA doesn't match.
4. The CMS catches the error and asks you to sync before saving.