Skip to content

Commit a93281a

Browse files
TooAngelTooAngel
authored
docs: restructure documentation for better navigation (#26)
- Rewrite README.md with clear navigation for three purposes: 1. Understanding the worlddriven idea (links to philosophy docs) 2. Architecture overview (links to new ARCHITECTURE.md) 3. Repository management (REPOSITORIES.md functionality) - Add ARCHITECTURE.md with: - System overview diagram - Component descriptions (core, webapp, documentation) - GitHub Apps explanation - Data flow diagrams (PR voting, migration, org sync) - Voting algorithm documentation - Update github-apps/README.md: - Link to architecture docs - Document backend implementation endpoints - Update worlddriven-migrate.json manifest: - Add installation event (fires on initial app install) - Keep installation_repositories event (fires on repo additions)
1 parent 5ab654a commit a93281a

4 files changed

Lines changed: 367 additions & 94 deletions

File tree

‎ARCHITECTURE.md‎

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
# Worlddriven Architecture
2+
3+
This document describes the high-level architecture of worlddriven. For implementation details, see the individual repository documentation.
4+
5+
## System Overview
6+
7+
```
8+
┌─────────────────────────────────────────────────────────────────────┐
9+
│ GitHub │
10+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
11+
│ │ User Repos │ │ worlddriven │ │ GitHub Apps │ │
12+
│ │ with WD app │ │ org repos │ │ (2 apps) │ │
13+
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
14+
└─────────┼─────────────────┼─────────────────┼───────────────────────┘
15+
│ webhooks │ │ installation
16+
▼ ▼ ▼
17+
┌─────────────────────────────────────────────────────────────────────┐
18+
│ Worlddriven Core │
19+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
20+
│ │ Webhook │ │ Voting │ │ Migration │ │
21+
│ │ Handler │ │ Engine │ │ Handler │ │
22+
│ └──────────────┘ └──────────────┘ └──────────────┘ │
23+
│ │ │
24+
│ ┌──────▼──────┐ │
25+
│ │ MongoDB │ │
26+
│ └─────────────┘ │
27+
└─────────────────────────────────────────────────────────────────────┘
28+
│
29+
▼
30+
┌─────────────────────────────────────────────────────────────────────┐
31+
│ Worlddriven Webapp │
32+
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
33+
│ │ Dashboard │ │ Repository │ │ OAuth │ │
34+
│ │ │ │ Management │ │ Flow │ │
35+
│ └──────────────┘ └──────────────┘ └──────────────┘ │
36+
└─────────────────────────────────────────────────────────────────────┘
37+
```
38+
39+
## Components
40+
41+
### Core (Backend)
42+
43+
**Repository**: [worlddriven/core](https://github.com/worlddriven/core)
44+
45+
The core backend handles all voting logic and GitHub integration:
46+
47+
| Component | Responsibility |
48+
|-----------|----------------|
49+
| **Webhook Handler** | Receives GitHub events (PR opened, review submitted, etc.) |
50+
| **Voting Engine** | Calculates merge coefficients based on time and reviews |
51+
| **Status Updates** | Posts commit statuses showing merge timeline |
52+
| **Auto-merge** | Merges PRs when voting threshold reached |
53+
| **Migration Handler** | Processes repository transfers via migrate app |
54+
55+
**Key Technologies**: Node.js, Express, MongoDB
56+
57+
### Webapp (Frontend)
58+
59+
**Repository**: [worlddriven/webapp](https://github.com/worlddriven/webapp)
60+
61+
The webapp provides the user interface:
62+
63+
| Component | Responsibility |
64+
|-----------|----------------|
65+
| **Dashboard** | Shows repositories and their PR status |
66+
| **Repository Management** | Enable/disable worlddriven, configure settings |
67+
| **OAuth Flow** | GitHub authentication |
68+
69+
**Key Technologies**: React, Vite
70+
71+
### Documentation (This Repository)
72+
73+
**Repository**: [worlddriven/documentation](https://github.com/worlddriven/documentation)
74+
75+
This repository serves dual purposes:
76+
77+
1. **Documentation** - Project philosophy, architecture, guides
78+
2. **Organization Management** - REPOSITORIES.md defines org structure
79+
80+
| Component | Responsibility |
81+
|-----------|----------------|
82+
| **REPOSITORIES.md** | Source of truth for org repositories |
83+
| **Automation Scripts** | Drift detection, sync, parsing |
84+
| **GitHub Actions** | Automated enforcement of desired state |
85+
| **GitHub App Manifests** | App configuration documentation |
86+
87+
**Key Technologies**: Node.js, GitHub Actions
88+
89+
## GitHub Apps
90+
91+
Worlddriven uses two GitHub Apps, following the principle of least privilege:
92+
93+
### WorldDriven (Main App)
94+
95+
**Purpose**: PR voting and auto-merge
96+
97+
**Permissions**:
98+
- `checks: write` - Create/update check runs
99+
- `contents: write` - Merge pull requests
100+
- `issues: write` - Comment on PRs
101+
- `metadata: read` - Basic repository info
102+
- `pull_requests: write` - Update PR status
103+
- `statuses: write` - Post commit statuses
104+
- `workflows: write` - Trigger workflow runs
105+
106+
**Events**:
107+
- `pull_request` - PR opened, closed, synchronized
108+
- `pull_request_review` - Review submitted
109+
- `push` - Code pushed
110+
111+
### WorldDriven Migrate
112+
113+
**Purpose**: One-time repository transfers to worlddriven org
114+
115+
**Permissions**:
116+
- `administration: write` - Transfer repositories
117+
- `metadata: read` - Basic repository info
118+
119+
**Events**:
120+
- `installation` - App installed (with repos)
121+
- `installation_repositories` - Repos added to existing installation
122+
123+
See [github-apps/](github-apps/) for manifest files.
124+
125+
## Data Flow
126+
127+
### PR Voting Flow
128+
129+
```
130+
1. User opens PR on repo with WorldDriven app installed
131+
│
132+
2. GitHub sends pull_request webhook to Core
133+
│
134+
3. Core calculates initial voting coefficient
135+
│ - Base merge time (configurable, default 10 days)
136+
│ - Per-commit time adjustment
137+
│
138+
4. Core posts commit status: "Merge at [date]"
139+
│
140+
5. Reviewer submits review (approve/request changes)
141+
│
142+
6. GitHub sends pull_request_review webhook to Core
143+
│
144+
7. Core recalculates coefficient
145+
│ - Fetch reviewer's contribution history
146+
│ - Calculate vote weight (commits / total commits)
147+
│ - Approve: reduces time, Request Changes: increases time
148+
│
149+
8. Core updates commit status with new merge date
150+
│
151+
9. When coefficient >= 1.0, Core merges the PR
152+
```
153+
154+
### Repository Migration Flow
155+
156+
```
157+
1. User adds entry to REPOSITORIES.md with Origin field
158+
│
159+
2. PR is created, reviewed, and merged via worlddriven voting
160+
│
161+
3. User installs WorldDriven Migrate app on their repo
162+
│
163+
4. GitHub sends installation webhook to Core
164+
│
165+
5. Migration Handler checks for approved migration PR
166+
│
167+
6. If approved, transfers repository to worlddriven org
168+
│
169+
7. Comments on PR and triggers CI re-run
170+
```
171+
172+
### Organization Sync Flow
173+
174+
```
175+
1. REPOSITORIES.md is modified
176+
│
177+
2. PR created and merged via worlddriven voting
178+
│
179+
3. GitHub Actions triggers sync workflow
180+
│
181+
4. Scripts parse REPOSITORIES.md (desired state)
182+
│
183+
5. Scripts fetch GitHub API (actual state)
184+
│
185+
6. Drift detection compares states
186+
│
187+
7. Sync applies changes to match desired state
188+
│
189+
8. Protected repos (documentation, core, webapp) skip destructive changes
190+
```
191+
192+
## Voting Algorithm
193+
194+
The voting coefficient determines when a PR merges:
195+
196+
```
197+
coefficient = time_factor + vote_factor
198+
199+
time_factor = hours_since_opened / base_merge_hours
200+
201+
vote_factor = Σ (vote_value × voter_weight)
202+
where:
203+
vote_value = +1 for approve, -1 for request changes
204+
voter_weight = voter_commits / total_repo_commits
205+
206+
PR merges when: coefficient >= 1.0
207+
```
208+
209+
### Example
210+
211+
- Base merge time: 240 hours (10 days)
212+
- PR open for 120 hours (5 days)
213+
- Reviewer A (10% of commits) approves: +0.1
214+
- Reviewer B (5% of commits) requests changes: -0.05
215+
216+
```
217+
coefficient = (120/240) + 0.1 - 0.05
218+
= 0.5 + 0.05
219+
= 0.55
220+
221+
PR needs coefficient >= 1.0, so it will wait longer or need more approvals.
222+
```
223+
224+
## Deployment
225+
226+
### Production URLs
227+
228+
| Service | URL |
229+
|---------|-----|
230+
| Main site | https://www.worlddriven.org |
231+
| API | https://www.worlddriven.org/api |
232+
| Webapp | https://worlddriven-webapp.tooangel.com |
233+
234+
### Infrastructure
235+
236+
- **Hosting**: Dokku on dedicated server
237+
- **Database**: MongoDB
238+
- **CI/CD**: GitHub Actions
239+
240+
## Security Considerations
241+
242+
### Vote Manipulation Prevention
243+
244+
- Vote weight based on historical commits (not easily faked)
245+
- All votes are public (GitHub reviews)
246+
- Transparent calculation shown in status
247+
248+
### Repository Protection
249+
250+
- Critical repos (documentation, core, webapp) have additional protections
251+
- Sync automation won't delete protected repos
252+
- Branch protection rules enforced
253+
254+
### App Permissions
255+
256+
- Minimal permissions per app (least privilege)
257+
- Separate app for admin operations (migration)
258+
- All webhook payloads verified
259+
260+
## Related Documentation
261+
262+
- [AUTOMATION.md](AUTOMATION.md) - Detailed automation guide
263+
- [REPOSITORIES.md](REPOSITORIES.md) - Repository configuration format
264+
- [scripts/README.md](scripts/README.md) - Script API reference
265+
- [github-apps/README.md](github-apps/README.md) - GitHub App details

0 commit comments

Comments
 (0)