From ddb07e68ecf5bda1eef14aade28c5105ba313285 Mon Sep 17 00:00:00 2001 From: AdeyinkaOresanya Date: Fri, 16 Jan 2026 12:14:09 +0100 Subject: [PATCH 1/3] docs: add Architecture Decision Record-001 for modularizing the Badging API architecture Signed-off-by: AdeyinkaOresanya --- .../001-adr-modular-badging-architecture.md | 199 ++++++++++++++++++ 1 file changed, 199 insertions(+) create mode 100644 docs/ADR/001-adr-modular-badging-architecture.md diff --git a/docs/ADR/001-adr-modular-badging-architecture.md b/docs/ADR/001-adr-modular-badging-architecture.md new file mode 100644 index 0000000..c5c81eb --- /dev/null +++ b/docs/ADR/001-adr-modular-badging-architecture.md @@ -0,0 +1,199 @@ +# ADR-001: Modularizing the Badging API Architecture + +## Status +Accepted + +## Date +2026-01-16 + +## Context + +The CHAOSS Badging API currently supports two distinct badging processes under the same badging program: + +- Event Badging +- Project Badging + +While both processes share a common website and some infrastructure (authentication, GitHub/GitLab integrations), they represent different workflows, data flows, and responsibilities. + +The current API codebase has several issues that affect that affect maintainability and clarity of process flow: + +- Event Badging and Project Badging logic are tightly coupled and co-located. +- There is no clear separation of concerns between HTTP handling, business logic, and data access. +- Contributors cannot easily determine which part of the system they are modifying. +- Code is duplicated. +- Names of files and modules are ambiguous. +- Files and functions are not clearly attributable to a specific process. +- Database operations, business logic, and HTTP handling are intermixed. +- Checklist generation and parsing logic is fragile and difficult to trace. +- Refactoring or adding features risks unintended side effects across processes. +Logic flow is hard to trace, making debugging and feature addition difficult. + + +These issues increase cognitive load, slow onboarding, slow and ineffective contributions, and make safe parallel development difficult. + +--- + +## Decision + +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 + +### 1. Modular Separation by Process + +The API will be structured around two top-level domains: + +- `event-badging` +- `project-badging` + +Each domain will encapsulate its own: +- Routes +- Controllers +- Services +- Data access logic +- Domain-specific models (where applicable) + +Shared infrastructure and cross-cutting concerns will live in a `shared` directory. + +--- + +### 2. Layered Architecture Within Each Module + +Each module will follow a consistent internal structure: + +``` + +/ +/routes → HTTP route definitions +/controllers → Request/response orchestration +/services → Business logic and workflows +/data-access → Database read/write operations +/models → ORM models and associations + +``` + +--- + +### 3. Introduction of a Dedicated Data Access Layer + +A dedicated Data Access Layer (DAL) will be introduced and named: + +``` + +data-access + +``` + +#### Rationale for Naming + +- Avoids confusion with GitHub/GitLab “repositories” +- Clearly communicates responsibility +- Aligns with standard backend architecture terminology +- Improves contributor understanding and onboarding + +#### Responsibilities of `data-access` + +- Perform database reads and writes +- Interact directly with ORM models +- Contain no business logic +- Contain no HTTP or framework-specific code + +Services must not interact with ORM models directly. + +--- + +### 4. Strict Responsibility Boundaries + +| Layer | Responsibility | +|-------------|----------------| +| Routes | Map URLs to controllers | +| Controllers | Handle HTTP concerns (req/res, status codes) | +| Services | Business rules, workflows, decisions | +| Data Access | Database persistence and queries | +| Models | Schema definitions and associations | + +Business logic resides only in services. + +Models remain declarative and must not contain: +- Workflow logic +- Formatting logic +- External API calls + +--- + +### 5. Shared Infrastructure + +Common components used by both domains will live under: + +``` + +/shared + +``` + +Including: +- Authentication providers +- External API clients (GitHub/GitLab) +- Shared models +- Shared data-access modules +- Common utilities + +Any change to shared code requires explicit review due to its cross-domain impact. + +--- + +## Consequences + +### Positive Outcomes + +- Clear ownership of Event Badging vs Project Badging code +- Safer parallel development by multiple contributors +- Improved testability through isolation of business logic +- Easier onboarding for new contributors +- Reduced risk of regressions during refactors +- Architecture that scales with new badging processes + +### Trade-offs + +- Initial refactor requires significant upfront time investment +- Requires contributors to follow stricter conventions +- Some boilerplate increases due to additional layers + +These trade-offs are accepted in favor of long-term maintainability and contributor clarity. + +--- + +## Implementation Plan + +1. Modularise the project to improve maintainability +2. Separate concerns between project badging and event badging by determining which scopes to have. +3. Write proper tests for the api +4. Improve security of the api and badging app by attending to the vulnerabilities of the packages +5. Resolve the issue of checkbox on ticking on event-diversity-and-inclusion repo +6. Deploy version 2.0 +--- + + +## Notes + +- Refactoring will be done incrementally to avoid breaking behavior. +- Files will be moved in small, verifiable steps with frequent commits. +- External integrations (GitHub/GitLab) will be mocked where possible during refactor. +- End-to-end integration testing will be performed after modularization. + +--- + +## Related Documents + +- Badging Data Flow Documentation +- Contributor Architecture Guide (planned) +- Refactoring Checklist (planned) + +--- + +## Decision Drivers + +- Maintainability +- Contributor clarity +- Safe parallel development +- Separation of concerns +- Long-term scalability of the badging program + From ff9c6e76b2d59d1d62569127d4e79a88ea0681c7 Mon Sep 17 00:00:00 2001 From: AdeyinkaOresanya Date: Fri, 16 Jan 2026 12:22:57 +0100 Subject: [PATCH 2/3] docs: add Product Requirements Document for Project Badging Signed-off-by: AdeyinkaOresanya --- docs/PRDs/project-badging-PRD.md | 118 +++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 docs/PRDs/project-badging-PRD.md diff --git a/docs/PRDs/project-badging-PRD.md b/docs/PRDs/project-badging-PRD.md new file mode 100644 index 0000000..ba78262 --- /dev/null +++ b/docs/PRDs/project-badging-PRD.md @@ -0,0 +1,118 @@ +# Product Requirements Document (PRD): Project Badging + +## Overview + +Project Badging is a process within the CHAOSS Badging Program that allows open source maintainers to earn a badge for their projects or communities by demonstrating the presence of DEI documentation in their repository. + +Unlike Event Badging, Project Badging is an automated validation process with no peer review. + +--- + +## Goals + +- Enable open source maintainers to apply for a DEI badge for their project/community +- Automatically validate the presence of required `DEI.md` file. +- Award badge based on `DEI.md` contents +- Provide fast feedback to applicants + +--- + +## Users + +- **Applicant / Maintainer**: Applies for a project badge +- **Badging Bot**: Scans repositories and awards a badge + +--- + +## Assumptions + +- Users authenticate using GitHub or GitLab +- The badging bot is granted access to user repositories +- DEI documentation is stored in a `DEI.md` file +- Badge eligibility is determined solely by the `DEI.md` contents + +--- + +## Functional Requirements + +### 1. Application Initiation + +- User clicks on “Apply for badge” on the Badging website +- User chooses to log in with GitHub or GitLab +- First-time users are asked to authorize access +- Returning users are authenticated automatically + +--- + +### 2. Repository Selection + +- After authentication: + - The user is redirected back to the website + - The system fetches all repositories accessible to the user + - The repositories are presented for selection + +--- + +### 3. Repository Scanning + +- Once a repository is selected: + - The badging bot scans the repository + - The bot searches for a `DEI.md` file + - The file is checked for required headings + +--- + +### 4. Badge Awarding + +- If `DEI.md` is found and meets requirements: + - The badge is awarded + - A success notification email containing the badge is sent to the user +- If not found or invalid: + - No badge is awarded + - An error or failure notification email is sent stating the reason + + +--- + +## Non-Functional Requirements + +- Repository scanning must be deterministic +- Authentication tokens must be handled securely +- The system must respect API rate limits +- The process must complete within reasonable time + +--- + +## Dependencies + +- GitHub OAuth +- GitLab OAuth +- GitHub App +- GitLab API +- Repository content APIs + +--- + +## Out of Scope + +- Manual review +- Partial scoring +- Review checklists +- Issue-based workflows + +--- + +## Success Metrics + +- Successful badge issuance for eligible repositories +- Clear feedback on failure reasons +- Minimal false positives or negatives + +## Future Version +- Awarding more than one level of badge (currently only one level, bronze, exists) + +--- + +## Notes + +Project Badging is intentionally automated and independent of Event Badging. While both processes share authentication and infrastructure, they must remain isolated at the business logic level to avoid unintended coupling. From 7c43b157b632038a531b54030201caaf74ee4b69 Mon Sep 17 00:00:00 2001 From: AdeyinkaOresanya Date: Fri, 16 Jan 2026 12:24:01 +0100 Subject: [PATCH 3/3] docs: add Product Requirements Document for Event Badging Signed-off-by: AdeyinkaOresanya --- docs/PRDs/event-badging-PRD.md | 128 +++++++++++++++++++++++++++++++++ 1 file changed, 128 insertions(+) create mode 100644 docs/PRDs/event-badging-PRD.md diff --git a/docs/PRDs/event-badging-PRD.md b/docs/PRDs/event-badging-PRD.md new file mode 100644 index 0000000..f3d69de --- /dev/null +++ b/docs/PRDs/event-badging-PRD.md @@ -0,0 +1,128 @@ +# Product Requirements Document (PRD): Event Badging + +## Overview + +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. + +This process is reviewer-driven, asynchronous, and fully auditable via GitHub. + +--- + +## Goals + +- Enable event organizers to apply for CHAOSS Event Badging +- Facilitate structured peer review using checklists +- Ensure transparent scoring and badge assignment +- Automate issue creation, review tracking, and badge awarding + +--- + +## Users + +- **Applicant**: Submits an event for badging +- **Reviewer**: Reviews the event application +- **Badging Bot**: Automates workflow actions +- **Badging lead/maintainer**: Oversees the badging process + +--- + +## Assumptions + +- GitHub is the source of truth for review activity +- GitHub authentication is required to apply +- Reviews are conducted through GitHub Issues +- A minimum of two reviewers is required + +--- + +## Functional Requirements + +### 1. Application Submission + +- User fills and submits the Event Badging form on the Badging website +- On submission, the user is redirected to GitHub for authentication +- GitHub requests authentication and authorization +- GitHub sends a temporary authorization code +- The server exchanges the code for an access token +- The system uses the access token to perform GitHub actions + +--- + +### 2. Issue Creation + +- The badging bot automatically creates a GitHub Issue in the `event-diversity-and-inclusion` repository +- The issue contains the submitted event application details +- The badging bot posts a thank-you comment acknowledging the application +- The bot begins listening for issue-related events + +--- + +### 3. Reviewer Assignment & Checklist + +- When a reviewer is assigned to the issue: + - The badging bot posts a review checklist as a comment + - Checklist headings are non-checkable + - Review items are checkable +- When two reviewers are assigned: + - The issue is automatically labeled `review-begin` + +--- + +### 4. Scoring and Results + +- When the badging lead comments `/result`: + - The badging bot calculates the percentage score + - Only checked boxes are counted + - The bot posts: + - Total percentage score + - Number of reviewers assigned + +--- + +### 5. Badge Assignment & Closure + +- When a reviewer comments `/end`: + - The badging bot: + - Assigns the appropriate badge + - Labels the issue `review-end` + - Closes the issue + +--- + +## Non-Functional Requirements + +- Checklist parsing must be accurate and deterministic +- Review calculations must be reproducible +- Workflow must be resilient to partial failures +- Actions must be traceable via GitHub issue history + +--- + +## Dependencies + +- GitHub OAuth +- GitHub App +- GitHub Issues API + +--- + +## Out of Scope + +- Manual badge assignment +- Review outside GitHub +- Fewer than two reviewers + +--- + +## Success Metrics + +- Successful badge issuance after completed reviews +- Accurate checklist parsing and scoring +- Reduced reviewer confusion +- Clear audit trail per application + +--- + +## Notes + +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.