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 + 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. 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.