Quill: Documentation Review
The Electron/React/TypeScript review app within ArmorCode's AI documentation automation, between agent-created GitHub PRs and publication to Zendesk.
- permission tiers enforced, all resolved from the source-control platform
- 3permission tiers enforced, all resolved from the source-control platform
- isolated working trees, so concurrent reviews never collide
- 1 per branchisolated working trees, so concurrent reviews never collide
- application-managed access lists to keep in sync
- 0application-managed access lists to keep in sync
Quill is the human review component of ArmorCode's AI documentation automation. When a Jira ticket is completed, an agent creates or updates documentation in GitHub and opens a PR. Reviewers use Quill to inspect rendered changes, edit the documentation and approve the proposal. After the PR merges, the surrounding workflow syncs the merged documentation to Zendesk. I built Quill in Electron, React and TypeScript to make that review step practical for the documentation team.
The problem
The Jira-triggered documentation agent already creates and updates articles through GitHub pull requests. Before Quill, the documentation team had to judge the proposed output through raw markup diffs and ask engineers to make small corrections. Since merged documentation is synchronized to Zendesk, review needed to let the people responsible for the articles inspect and fix the actual draft before publication.
Constraints
- Several proposals are open at once, so editing one cannot disturb the working copy of another.
- Reviewers are not engineers; anything requiring command-line work would not be used.
- Access control must not become a second system to keep in sync with the source of truth.
- Reviewers need to see what customers will see, not an approximation of it.
- Quill reviews the GitHub documentation PR; authoring is triggered by Jira completion and Zendesk synchronization happens after merge in the surrounding workflow.
Architecture
Decisions
What I chose, why, and what I turned down to get there.
A separate working tree per proposal
Each open branch gets its own checkout, so the primary copy is never modified and parallel reviews cannot collide. Editing in place on a shared checkout is the obvious implementation and the one that corrupts state the first time two reviews overlap. Paths are validated to prevent traversal outside the intended directory.
Considered and rejected
- Editing directly in a single shared checkout — simpler until two people review at once, then wrong in ways that are hard to unwind
Delegate permissions entirely to the source-control platform
The app resolves the user's live permission tier and adapts: read-only reviewers can view but not edit or merge, write access unlocks editing, and full access unlocks merging. There is no in-app access list, so adding a collaborator in one place grants the right level everywhere. A duplicated permission model is a permission model that drifts, and drift in access control is a security bug.
Considered and rejected
- An application-managed access list — one more thing to maintain, and it would diverge
Render in the real published theme
The published styling is vendored so the side-by-side comparison shows what readers will actually get, with word-level highlighting. A reviewer approving documentation is approving how it reads in context, which a markup diff cannot show and which is exactly where errors of tone and structure hide.
Embed a real terminal, not a simulated one
A genuine terminal session opens in the active working tree so a reviewer can re-run the authoring agent on the spot rather than filing a request and waiting. The loop that matters is see a problem, fix the source of the problem, review again — and that loop only closes if the agent is reachable from where the review happens.
Quill's place in the documentation workflow
The workflow begins outside Quill, when a completed Jira ticket triggers the documentation agent. The agent creates or updates articles in GitHub and opens a PR. Quill brings those PRs to the documentation team for rendered review, editing and approval. Once a PR merges, the documentation synchronization workflow updates Zendesk. This case study focuses on the review app within that larger system.
What shipped in the review app
A working desktop application covering the full review path: a filtered list of open proposals, rendered side-by-side comparison with inline and multi-line comments that post back to the real pull request, approve and merge as genuine actions, a searchable article browser with version preview, an in-place editor with image management committed atomically alongside the text, a command palette for jumping to any article, a conversation timeline, and automated builds attaching signed installers to releases.
- Inline suggestions are posted in the platform's native suggestion format, so a reviewer's fix becomes a one-click accept rather than a comment someone has to transcribe.
- Quill is an internal release within the production documentation automation workflow. Jira completion triggers authoring, Quill supports review, and merged documentation is synced to Zendesk.
Stack
- Electron
- React
- TypeScript
- Git
- GitHub API
- TinyMCE
- node-pty
- GitHub Actions
What was mine
Designed and built Quill, the review application within the documentation automation platform, from the first proposal through release automation. Its scope is inspecting, editing and approving GitHub documentation PRs; the surrounding pipeline handles the Jira trigger, agent authoring and Zendesk synchronization after merge. The documentation team owns the review decisions.