Skip to content

Commit dd576cf

Browse files
DesmondSanctityDesmondSanctity
authored
Merge pull request #59 from adeyinkaoresanya/adeyinka-documentation
Add ADR and Detailed PRDs for Modular CHAOSS Badging API
2 parents d6f3e75 + 7c43b15 commit dd576cf

File tree

3 files changed

+445
-0
lines changed

3 files changed

+445
-0
lines changed

‎docs/ADR/001-adr-modular-badging-architecture.md‎

Lines changed: 199 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,199 @@
1+
# ADR-001: Modularizing the Badging API Architecture
2+
3+
## Status
4+
Accepted
5+
6+
## Date
7+
2026-01-16
8+
9+
## Context
10+
11+
The CHAOSS Badging API currently supports two distinct badging processes under the same badging program:
12+
13+
- Event Badging
14+
- Project Badging
15+
16+
While both processes share a common website and some infrastructure (authentication, GitHub/GitLab integrations), they represent different workflows, data flows, and responsibilities.
17+
18+
The current API codebase has several issues that affect that affect maintainability and clarity of process flow:
19+
20+
- Event Badging and Project Badging logic are tightly coupled and co-located.
21+
- There is no clear separation of concerns between HTTP handling, business logic, and data access.
22+
- Contributors cannot easily determine which part of the system they are modifying.
23+
- Code is duplicated.
24+
- Names of files and modules are ambiguous.
25+
- Files and functions are not clearly attributable to a specific process.
26+
- Database operations, business logic, and HTTP handling are intermixed.
27+
- Checklist generation and parsing logic is fragile and difficult to trace.
28+
- Refactoring or adding features risks unintended side effects across processes.
29+
Logic flow is hard to trace, making debugging and feature addition difficult.
30+
31+
32+
These issues increase cognitive load, slow onboarding, slow and ineffective contributions, and make safe parallel development difficult.
33+
34+
---
35+
36+
## Decision
37+
38+
We will refactor the Badging API to adopt a modular, layered architecture with explicit separation of concerns. This is necessary to improve the stability, clarity, and maintainability of the Badging System
39+
40+
### 1. Modular Separation by Process
41+
42+
The API will be structured around two top-level domains:
43+
44+
- `event-badging`
45+
- `project-badging`
46+
47+
Each domain will encapsulate its own:
48+
- Routes
49+
- Controllers
50+
- Services
51+
- Data access logic
52+
- Domain-specific models (where applicable)
53+
54+
Shared infrastructure and cross-cutting concerns will live in a `shared` directory.
55+
56+
---
57+
58+
### 2. Layered Architecture Within Each Module
59+
60+
Each module will follow a consistent internal structure:
61+
62+
```
63+
64+
/<domain>
65+
/routes → HTTP route definitions
66+
/controllers → Request/response orchestration
67+
/services → Business logic and workflows
68+
/data-access → Database read/write operations
69+
/models → ORM models and associations
70+
71+
```
72+
73+
---
74+
75+
### 3. Introduction of a Dedicated Data Access Layer
76+
77+
A dedicated Data Access Layer (DAL) will be introduced and named:
78+
79+
```
80+
81+
data-access
82+
83+
```
84+
85+
#### Rationale for Naming
86+
87+
- Avoids confusion with GitHub/GitLab “repositories”
88+
- Clearly communicates responsibility
89+
- Aligns with standard backend architecture terminology
90+
- Improves contributor understanding and onboarding
91+
92+
#### Responsibilities of `data-access`
93+
94+
- Perform database reads and writes
95+
- Interact directly with ORM models
96+
- Contain no business logic
97+
- Contain no HTTP or framework-specific code
98+
99+
Services must not interact with ORM models directly.
100+
101+
---
102+
103+
### 4. Strict Responsibility Boundaries
104+
105+
| Layer | Responsibility |
106+
|-------------|----------------|
107+
| Routes | Map URLs to controllers |
108+
| Controllers | Handle HTTP concerns (req/res, status codes) |
109+
| Services | Business rules, workflows, decisions |
110+
| Data Access | Database persistence and queries |
111+
| Models | Schema definitions and associations |
112+
113+
Business logic resides only in services.
114+
115+
Models remain declarative and must not contain:
116+
- Workflow logic
117+
- Formatting logic
118+
- External API calls
119+
120+
---
121+
122+
### 5. Shared Infrastructure
123+
124+
Common components used by both domains will live under:
125+
126+
```
127+
128+
/shared
129+
130+
```
131+
132+
Including:
133+
- Authentication providers
134+
- External API clients (GitHub/GitLab)
135+
- Shared models
136+
- Shared data-access modules
137+
- Common utilities
138+
139+
Any change to shared code requires explicit review due to its cross-domain impact.
140+
141+
---
142+
143+
## Consequences
144+
145+
### Positive Outcomes
146+
147+
- Clear ownership of Event Badging vs Project Badging code
148+
- Safer parallel development by multiple contributors
149+
- Improved testability through isolation of business logic
150+
- Easier onboarding for new contributors
151+
- Reduced risk of regressions during refactors
152+
- Architecture that scales with new badging processes
153+
154+
### Trade-offs
155+
156+
- Initial refactor requires significant upfront time investment
157+
- Requires contributors to follow stricter conventions
158+
- Some boilerplate increases due to additional layers
159+
160+
These trade-offs are accepted in favor of long-term maintainability and contributor clarity.
161+
162+
---
163+
164+
## Implementation Plan
165+
166+
1. Modularise the project to improve maintainability
167+
2. Separate concerns between project badging and event badging by determining which scopes to have.
168+
3. Write proper tests for the api
169+
4. Improve security of the api and badging app by attending to the vulnerabilities of the packages
170+
5. Resolve the issue of checkbox on ticking on event-diversity-and-inclusion repo
171+
6. Deploy version 2.0
172+
---
173+
174+
175+
## Notes
176+
177+
- Refactoring will be done incrementally to avoid breaking behavior.
178+
- Files will be moved in small, verifiable steps with frequent commits.
179+
- External integrations (GitHub/GitLab) will be mocked where possible during refactor.
180+
- End-to-end integration testing will be performed after modularization.
181+
182+
---
183+
184+
## Related Documents
185+
186+
- Badging Data Flow Documentation
187+
- Contributor Architecture Guide (planned)
188+
- Refactoring Checklist (planned)
189+
190+
---
191+
192+
## Decision Drivers
193+
194+
- Maintainability
195+
- Contributor clarity
196+
- Safe parallel development
197+
- Separation of concerns
198+
- Long-term scalability of the badging program
199+

‎docs/PRDs/event-badging-PRD.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Product Requirements Document (PRD): Event Badging
2+
3+
## Overview
4+
5+
Event Badging is a process within the CHAOSS Badging Program that allows event organizers to apply for a DEI-related badge. Applications are submitted via the Badging website and reviewed by assigned reviewers through a GitHub Issue–based workflow managed by a badging bot.
6+
7+
This process is reviewer-driven, asynchronous, and fully auditable via GitHub.
8+
9+
---
10+
11+
## Goals
12+
13+
- Enable event organizers to apply for CHAOSS Event Badging
14+
- Facilitate structured peer review using checklists
15+
- Ensure transparent scoring and badge assignment
16+
- Automate issue creation, review tracking, and badge awarding
17+
18+
---
19+
20+
## Users
21+
22+
- **Applicant**: Submits an event for badging
23+
- **Reviewer**: Reviews the event application
24+
- **Badging Bot**: Automates workflow actions
25+
- **Badging lead/maintainer**: Oversees the badging process
26+
27+
---
28+
29+
## Assumptions
30+
31+
- GitHub is the source of truth for review activity
32+
- GitHub authentication is required to apply
33+
- Reviews are conducted through GitHub Issues
34+
- A minimum of two reviewers is required
35+
36+
---
37+
38+
## Functional Requirements
39+
40+
### 1. Application Submission
41+
42+
- User fills and submits the Event Badging form on the Badging website
43+
- On submission, the user is redirected to GitHub for authentication
44+
- GitHub requests authentication and authorization
45+
- GitHub sends a temporary authorization code
46+
- The server exchanges the code for an access token
47+
- The system uses the access token to perform GitHub actions
48+
49+
---
50+
51+
### 2. Issue Creation
52+
53+
- The badging bot automatically creates a GitHub Issue in the `event-diversity-and-inclusion` repository
54+
- The issue contains the submitted event application details
55+
- The badging bot posts a thank-you comment acknowledging the application
56+
- The bot begins listening for issue-related events
57+
58+
---
59+
60+
### 3. Reviewer Assignment & Checklist
61+
62+
- When a reviewer is assigned to the issue:
63+
- The badging bot posts a review checklist as a comment
64+
- Checklist headings are non-checkable
65+
- Review items are checkable
66+
- When two reviewers are assigned:
67+
- The issue is automatically labeled `review-begin`
68+
69+
---
70+
71+
### 4. Scoring and Results
72+
73+
- When the badging lead comments `/result`:
74+
- The badging bot calculates the percentage score
75+
- Only checked boxes are counted
76+
- The bot posts:
77+
- Total percentage score
78+
- Number of reviewers assigned
79+
80+
---
81+
82+
### 5. Badge Assignment & Closure
83+
84+
- When a reviewer comments `/end`:
85+
- The badging bot:
86+
- Assigns the appropriate badge
87+
- Labels the issue `review-end`
88+
- Closes the issue
89+
90+
---
91+
92+
## Non-Functional Requirements
93+
94+
- Checklist parsing must be accurate and deterministic
95+
- Review calculations must be reproducible
96+
- Workflow must be resilient to partial failures
97+
- Actions must be traceable via GitHub issue history
98+
99+
---
100+
101+
## Dependencies
102+
103+
- GitHub OAuth
104+
- GitHub App
105+
- GitHub Issues API
106+
107+
---
108+
109+
## Out of Scope
110+
111+
- Manual badge assignment
112+
- Review outside GitHub
113+
- Fewer than two reviewers
114+
115+
---
116+
117+
## Success Metrics
118+
119+
- Successful badge issuance after completed reviews
120+
- Accurate checklist parsing and scoring
121+
- Reduced reviewer confusion
122+
- Clear audit trail per application
123+
124+
---
125+
126+
## Notes
127+
128+
Event Badging is a review-driven process and differs significantly from Project Badging in both workflow and automation requirements. The two processes share authentication and infrastructure but must remain logically independent.

0 commit comments

Comments
 (0)