Engineering Contribution Guidelines & Code Standards

This document is the authoritative standard for contributing to the Debelu codebase. Grounded directly in [package.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/package.json), [eslint.config.base.js](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/eslint.config.base.js), [.prettierrc](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/.prettierrc), and our CI/CD quality gates, this guide governs git branching, code style, testing mandates, and architectural invariants.

---

1. Branching Strategy & Pull Request Lifecycle

Debelu follows a disciplined Trunk-Based Development model with short-lived feature branches and strict CI validation on pull requests.

gitGraph
    commit id: "v1.0.0"
    branch feat/escrow-reversal
    checkout feat/escrow-reversal
    commit id: "feat(backend): add reversal service"
    commit id: "test(db): add concurrency check"
    checkout main
    merge feat/escrow-reversal id: "PR #142 (Squash & Merge)"
    branch fix/cart-kobo-calc
    checkout fix/cart-kobo-calc
    commit id: "fix(storefront): integer kobo rounding"
    checkout main
    merge fix/cart-kobo-calc id: "PR #143 (Squash & Merge)"

1.1 Branch Naming Conventions

Branch names must reflect the intent and workspace:

• feat/<scope>-<description>: New platform capabilities (e.g., feat/backend-campus-hubs, feat/storefront-nduzi-modal).
• fix/<scope>-<description>: Defect resolutions (e.g., fix/storefront-kobo-rounding, fix/backend-paystack-timeout).
• refactor/<scope>-<description>: Code improvements without behavior changes (e.g., refactor/core-type-cleanup).
• perf/<scope>-<description>: Performance and latency optimizations (e.g., perf/catalog-query-indexes).
• docs/<description>: Documentation additions or updates (e.g., docs/api-reference-update).

1.2 Pull Request Standards

1. Single Responsibility: Each pull request must focus on a discrete feature or bugfix. Do not combine architectural refactoring with commercial feature additions.
2. Automated CI Pass: Every pull request must pass the full monorepo-ci.yml pipeline (type-check, lint, test, build, and database tests) before review.
3. Required Approvals:
   • Standard PRs: Minimum 1 peer review approval.
   • Financial / Auth / RLS PRs: Mandatory approval from Principal Backend Architect or Security Lead.

---

2. Automated Quality Gates (npm run check)

Prior to opening a pull request or pushing code to remote branches, developers must execute the master pre-push verification script at the monorepo root:

# Runs type-check, lint, unit tests, and production builds across all workspaces
npm run check

flowchart TD
    RunCheck[npm run check] --> Step1[1. Type-Check: tsc --noEmit across all workspaces]
    Step1 --> Step2[2. Lint: ESLint 9 Flat Config inspection]
    Step2 --> Step3[3. Tests: Vitest & Jest unit test suites]
    Step3 --> Step4[4. Build: Production bundle compilation via Turbo]
    Step4 --> Pass[Clean Exit: Ready for Pull Request]

---

3. Engineering & Code Style Standards

3.1 Strict TypeScript Invariants

Debelu operates under strict TypeScript compiler rules (tsconfig.base.json):

• Zero Explicit any: The use of any is prohibited. Use unknown with runtime type narrowing (e.g., Zod schemas or type guards) when input data types are uncertain.
• Explicit Type Imports: Always import types using import type { ... } syntax (verbatimModuleSyntax: true).
• Array Indexing Safety: With noUncheckedIndexedAccess: true, all array lookups (items[0]) evaluate to T | undefined and require explicit guards.

3.2 Code Formatting (Prettier)

Code formatting is strictly automated. Developers should configure "Format on Save" in their IDEs:

// .prettierrc
{
  "singleQuote": true,
  "trailingComma": "all",
  "tabWidth": 2,
  "semi": true,
  "printWidth": 100
}

3.3 Linting Standards (ESLint 9 Flat Config)

All code must pass [eslint.config.base.js](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/eslint.config.base.js) checks:

• No unused variables or imports.
• Proper React hook dependency arrays (react-hooks/exhaustive-deps).
• No direct DOM mutations in React components.

---

4. Architectural Rules & Invariants

4.1 Design System Invariant (DESIGN.md)

• Strict Reuse of @debelu/ui: Client applications (apps/storefront, debelu-marketing) must never declare local CSS color overrides, ad-hoc hex codes, or duplicate button/input primitives. Visual elements must be imported from @debelu/ui.

4.2 Centralization of Domain Logic (@debelu/core)

• Shared interfaces, Zod schemas, and client service helpers belong in @debelu/core. Never duplicate data models across frontend and backend workspaces.

4.3 Backend 3-Tier Separation of Concerns

In debelu-backend, logic must follow the deterministic pipeline: $$\text{Route (Validation & Rate Limits)} \longrightarrow \text{Controller (HTTP Protocol)} \longrightarrow \text{Domain Service (Business Invariants)} \longrightarrow \text{PostgreSQL / External API}$$ Controllers must remain lean; complex business logic, database transactions, and third-party integrations belong exclusively in src/services/.

4.4 Database Migration Immutability

• Never edit an existing file in supabase/migrations/.
• All schema modifications must be applied via forward-only, idempotent timestamped migrations (YYYYMMDDHHMMSS_name.sql).

---

5. Mandatory Testing Policy

CAUTION

PULL REQUESTS MODIFYING FINANCIAL CODE WITHOUT TESTS WILL BE REJECTED AUTOMATICALLY.

5.1 When a Test is Required

1. Financial Logic: Any code touching orders, escrow locking, delivery PIN verification, Paystack charges, wallets, or payouts requires unit tests asserting calculation accuracy in Kobo.
2. Access Control & RLS: Any modification to Row-Level Security policies or staff roles must be verified via an automated check in scripts/db-*-checks.mjs.
3. API Endpoints: New Express routes must provide integration tests verifying valid 200/201 responses, validation failure 400s, and unauthorized 401/403 responses.
4. Interactive UI Components: New compound components in @debelu/ui require React Testing Library component tests.

---

6. Conventional Commit Message Specification

Debelu enforces the Conventional Commits standard. Commit messages must follow the format:

<type>(<scope>): <short_summary>

[optional body explaining rationale and non-obvious context]

[optional footer: Closes #123, BREAKING CHANGE: ...]

6.1 Allowed Types & Examples

• feat(backend): Add Paystack dedicated virtual account resolver.
• fix(storefront): Prevent floating-point rounding error in cart subtotal calculation.
• perf(database): Add partial compound index on orders(operation_campus, status).
• refactor(core): Migrate order status strings to strict TypeScript union type.
• test(db): Add concurrency race condition test for product stock reservations.
• docs(api): Document RFC 7807 problem details error catalog.

---

7. Documentation Synchronization Invariant

Code and documentation must evolve together in the same pull request:

• Adding or modifying a REST route $\rightarrow$ Update [docs/reference/api-endpoints.md](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/docs/reference/api-endpoints.md).
• Adding or modifying a database table/column $\rightarrow$ Update [docs/reference/database-schema.md](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/docs/reference/database-schema.md).
• Adding or modifying an environment variable $\rightarrow$ Update .env.example and [docs/reference/environment-variables.md](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/docs/reference/environment-variables.md).

---

8. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal Staff Engineer	Initial enterprise contribution guidelines covering branching, automated quality gates, TypeScript strictness, architecture rules, testing mandates, and commit conventions.	Active Living Standard