Many organizations – NGOs, associations, initiatives, editorial teams, political organizations, as well as companies – produce large amounts of structured digital content: internal documentation, policies, protocols, resolutions, position papers, as well as external artifacts such as letters, invitations, or documents following a strict corporate design (for example via Typst or Markdown templates).
From a technical perspective, Git, Markdown, CI/CD, and AI are well suited to manage this content in a versioned, auditable, and highly automated way. In practice, however, these workflows often fail due to accessibility: GitHub is powerful, but for many contributors it is too complex, English-only, and cognitively overwhelming.
The result is a familiar split: a small technical core works “in the system”, while most of the organization is excluded and falls back to email, Word documents, and manual coordination.
This document describes an architecture intended to close that gap without weakening technical workflows.
- Use GitHub as the single source of truth
- Avoid parallel systems or shadow state
- Enable participation by non-technical stakeholders
- Preserve existing technical workflows
- Integrate AI-supported document creation and maintenance
- GitHub is the single source of truth
- No independent persistent business state
- The frontend is a pure UX abstraction
- Read ≠ write (strict token separation)
- Webhooks instead of polling
- Pull requests are implementation details, not UX objects
- domain experts, decision makers, contributors
- little or no English proficiency
- want to read, comment, and initiate work
- need guidance rather than feature density
- work directly in GitHub
- use issues, pull requests, actions, and AI workflows
- accept Git as the working model and source of truth
US-S1: Read and comment on discussions
As a stakeholder, I want to read a discussion and post a comment without having to understand GitHub.
US-S2: Formulate a task
As a stakeholder, I want to formulate a task (e.g. “Please draft an invitation letter”) and know that it enters the system in a structured way.
US-S3: See results
As a stakeholder, I want to see outcomes (preview links, documents, status updates) without dealing with pull requests or commits.
US-T1: Preserve technical freedom
As technical staff, I want to continue working directly with issues, pull requests, and commits.
US-T2: Clean separation of concerns
As a maintainer, I want domain discussion to stay in issues and technical detail in pull requests.
Astro Frontend (localized, simplified)
↓
Aggregation / UX Layer
↓
GitHub API
- Issues
- Discussions
- Comments
- Pull Requests
- Actions / Bots
- GitHub App (installation token)
- high rate limits
- no user context
- GitHub OAuth App (user token)
- used only for comments and issue creation
- tokens stored server-side only
- no polling
- delta sync via webhooks
- relevant events:
issues.*issue_comment.*discussion.*pull_request.*
- no standalone or persistent AI agents
- AI reacts only to GitHub events
- triggers via comments (e.g.
@claude) - AI produces commits, pull requests, and comments back to GitHub
- pull requests are invisible in the frontend
- results are mirrored via bot comments in issues
- selective preview links, including monorepo setups
- read operations via app tokens
- write operations minimized via user tokens
- GraphQL + batching
- aggressive caching
- webhooks instead of polling
- mapping logic (issue → task)
- comment parsing
- diff analysis
- mocked GitHub API
- pagination and error handling
- dedicated GitHub test organization
- test repository
- test OAuth app
- test GitHub app
- not a classic forum
- not a CMS
- not a Jira replacement
- no custom IAM
- no separate user database
⚠️ Complete AI implementation contract (copy verbatim)
You are an implementation AI.
Your task is to build a GitHub-backed collaboration platform.
HARD CONSTRAINTS:
- GitHub is the only source of truth.
- No independent business state.
- No user database.
- No passwords.
- No polling.
- No reimplementation of the GitHub UI.
ARCHITECTURE:
- Frontend: Astro, server-side rendered, minimal client JS.
- Backend: aggregation layer with caching only (no state).
- GitHub App:
- used for all read access
- used for receiving webhooks
- GitHub OAuth App:
- used only for writing comments and creating issues in the name of users
STATE MODEL:
- All visible state is derived from GitHub.
- Caches may exist but must be invalidated via webhooks.
- No mutation outside GitHub APIs.
UX RULES:
- UI language: English (localizable).
- Role-based views:
- Stakeholders: discussions, tasks (issues), comments, results.
- Technical staff: work directly in GitHub.
- Never expose:
- Pull requests
- Commits
- Branches
- Labels
- Milestones
AI INTEGRATION:
- No standalone or long-lived agents.
- AI reacts only to GitHub events (e.g. issue comments).
- AI outputs:
- commits
- pull requests
- comments
- All AI output must be written back to GitHub.
TESTING REQUIREMENTS:
- Unit tests:
- mapping logic
- comment parsing
- diff analysis
- Contract tests:
- mocked GitHub API
- pagination
- error handling
- End-to-end tests:
- real GitHub test organization
- real repositories
- real GitHub App installation
- real OAuth flow
RATE LIMIT STRATEGY:
- Prefer GitHub App tokens for reads.
- Use OAuth user tokens only for writes.
- Batch requests via GraphQL.
- Cache aggressively.
- Rely on webhooks instead of polling.
GOAL:
Enable non-technical stakeholders to participate in GitHub-backed collaboration
without weakening or abstracting away technical workflows.