specgit architecture
How specgit works
specgit is deliberately thin: a visual editor and a review workflow layered on primitives GitHub already provides. There is no document database to trust us with — saves are commits, comments are pull request threads, publish is a merge. This page walks through the three pieces that make that work.
Your browser — the visual editor
Each open document is a live collaborative document: your edits, your teammates' cursors, and inline comments merge conflict-free in real time.
Real-time collaboration service — temporary co-editing state
A real-time collaboration service relays edits between everyone in the doc. Its state is a working buffer only: deleted after publish or direct commit, swept after up to 7 days of inactivity.
specgit server — the GitHub broker
Authenticates you through the specgit GitHub App, verifies repo access before minting any realtime token, and translates editor actions into commits, branches, pull requests, and merges. It keeps no copy of your documents.
Your GitHub repository — the only source of truth
Documents, comments, review history, and approvals live here as plain Markdown/HTML files, commits, and pull requests — readable by every other tool, engineer, and AI coding agent.
Step 1 — Access: a fine-grained GitHub App, repo by repo
All sign-in goes through the specgit GitHub App — there is no separate password and no broad OAuth grant. You (or your organization's admin) choose exactly which repositories the installation can reach, and tokens are short-lived. The App requests four narrow permissions:
- Contents (Read & write) — Read the Markdown and HTML files people open, and save their edits back as ordinary git commits on review branches.
- Pull requests (Read & write) — Open a pull request for each draft, post review comments, and merge when someone publishes.
- Issues (Read & write) — Post and read the discussion comments on those pull requests (GitHub serves PR-level comments through its issues API).
- Metadata (Read-only) — List the repositories the installation grants — the mandatory baseline permission for every GitHub App.
The installation cannot change repository settings, branch protections, or webhooks; manage collaborators, teams, deploy keys, or invitations; reach any repository outside the ones the installation grants. The full permission brief — written for the person who has to approve it — is on the page for IT admins.
Step 2 — Live co-editing: conflict-free, in real time
When you open a document, the editor loads it into a live collaborative document built for conflict-free live editing — any number of people can edit simultaneously without overwriting each other. A real-time collaboration service relays those edits between everyone in the room.
Getting into a room is brokered, not open: the specgit server first verifies — with your own GitHub token — that you can actually access the repository, then mints a short-lived client token for a room whose id is derived server-side from the verified document reference. Clients can never request a token for an arbitrary room, and the browser never holds the realtime server's secret.
Realtime state is temporary working state on our servers, not a copy of record: it is deleted after publish or direct commit, and inactive rooms are swept after up to 7 days.
Step 3 — Persistence: everything becomes a GitHub primitive
specgit doesn't invent its own storage or review model — it maps every editor action onto the GitHub primitive your engineers already trust:
Save
A git commit on a review branch
Every save is an ordinary commit attributed to the person who made it — full history, exact diffs, undo to any point.
Comment
A pull request review thread
Highlight text and comment; the thread is a real PR review conversation engineers can answer from GitHub or from specgit.
Ask for review
A pull request review
Approvals count toward branch protection and required-review rules; self-approval is prevented, just like on GitHub.
Publish
A merge to your base branch
Publishing merges the draft — the same flow engineers use to ship code. “Publish when approved” arms GitHub auto-merge.
Branch protection and required reviews work end to end: specgit reads the repository's rules and shows exactly what's blocking a publish ("needs 2 approving reviews — 1 so far") instead of failing mysteriously. Renames are true git renames, so history follows the file.
What this architecture never does
The privacy promises on the homepage aren't policy bolted onto a product — they fall out of the architecture:
- Your documents never leave your GitHub — specgit keeps no long-term copy and runs no document database.
- No product analytics, ad tracking, or third-party tracking scripts — ever.
- Your content is never used to train AI models. The optional specgit AI runs only when you invoke it, and every AI-proposed change requires your approval.
- Server logs are metadata only — timings, ids, and counts, never document text.
The full data-handling story — token encryption, retention windows, and what the AI provider sees — is on Security and data privacy.
See it work on your own docs
Open any Markdown or HTML doc already in your GitHub — fine-grained access you approve on GitHub, nothing to set up.
Free to start, no credit card. Your docs never leave GitHub.
By continuing, you agree to the Terms of Use and Privacy Policy.
Frequently asked questions
Where do my documents live?
In your GitHub repository, always. specgit reads files from GitHub when you open them and writes edits back as commits, branches, pull requests, and comments. There is no specgit document database — stop using specgit anytime and everything is already in your repo.
What happens to the live co-editing state?
Live collaboration uses a real-time collaboration service that keeps temporary working state on our servers so multiple people can edit together. That state is deleted after publish or direct commit, and inactive rooms are swept after up to 7 days. It is a working buffer, not a copy of record.
Can specgit reach repositories I didn't grant?
No. Sign-in goes through the specgit GitHub App with fine-grained, repo-by-repo permissions and short-lived tokens. The App can only reach the repositories you (or your organization's admin) explicitly grant to the installation, and access is revocable anytime from GitHub's settings.
Does the server keep my content or train models on it?
No. specgit keeps no long-term copy of documents, runs no product analytics or tracking scripts, and never uses your content to train AI models. The optional specgit AI features run only when you invoke them, and every AI-proposed change requires your approval.