Monorepo Architecture & Development Workflow

This document is the authoritative engineering specification for developer workflows, package boundaries, caching mechanisms, and release patterns within the Debelu monorepo. Grounded directly in the root [package.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/package.json), [turbo.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/turbo.json), [tsconfig.base.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/tsconfig.base.json), and shared workspace libraries, this guide governs how multi-surface code is authored, linked, and verified.

---

1. Monorepo Topology & Workspace Boundaries

Debelu operates as an npm workspaces monorepo containing 4 applications and 2 shared foundational packages:

graph TD
    subgraph SharedPackages [Shared Foundations: packages/*]
        Core["@debelu/core<br/>Domain Types (44KB), Services, Schemas, i18n"]
        UI["@debelu/ui<br/>Design System, theme.css, Components, Modals"]
    end

    subgraph ClientApplications [Client Surfaces: apps/* & debelu-*]
        Storefront["@debelu/storefront (apps/storefront)<br/>React 19 / Vite 6 Buyer & Vendor SPA + Capacitor"]
        Marketing["debelu-marketing<br/>Next.js 16 App Router Public SEO & Auth Portal"]
        Admin["debelu-admin<br/>Vite / React Isolated Operations Console"]
    end

    subgraph BackendAPI [Core Backend Platform]
        Backend["debelu-backend<br/>Express 4 / Node 20 REST API & Background Daemons"]
    end

    Core --> UI
    Core --> Storefront
    Core --> Marketing
    Core --> Admin
    Core --> Backend
    
    UI --> Storefront
    UI --> Marketing
    UI --> Admin

1.1 Workspace Directory Manifest

Workspace Directory	Package Name	Architectural Role & Runtime
packages/core	@debelu/core	Universal business logic, domain types (types.ts), client services, validation schemas, and telemetry bridges.
packages/ui	@debelu/ui	Design system tokens (theme.css), reusable Radix/Tailwind components, icons, toasts, and maintenance screens.
apps/storefront	@debelu/storefront	Primary consumer marketplace (buyer & vendor portals) with Capacitor Android/iOS wrappers.
debelu-marketing	debelu-marketing	Public apex portal (debelu.com), Next.js 16 App Router, SEO indexing, and authentication gateways.
debelu-admin	debelu-admin	Strictly segregated internal operations console (admin.debelu.com) for staff governance.
debelu-backend	debelu-backend	Authoritative REST API service (api.debelu.com), BullMQ queues, and database orchestration.

---

2. npm Workspaces & Dependency Orchestration

Debelu relies on native npm workspaces ([email protected]). Workspace packages are symlinked automatically into the root node_modules/, allowing instant hot-reloading across packages without compilation steps during local development.

2.1 Workspace Command Execution Patterns

# Execute a script inside a specific workspace
npm run <script> --workspace=<workspace_name>
# Examples:
npm run dev --workspace=debelu-backend
npm run build --workspace=@debelu/storefront

# Execute a script across ALL workspaces that define it
npm run type-check --workspaces --if-present
npm run lint --workspaces --if-present

# Add a third-party dependency to a specific workspace
npm install date-fns --workspace=@debelu/storefront

# Add a shared devDependency to the monorepo root
npm install -D vitest --save-exact

2.2 Strict Dependency Overrides (package.json)

To prevent duplicate React runtimes across monorepo symlinks, the root package.json enforces global package pinning:

"overrides": {
  "react": "^19.2.8",
  "react-dom": "^19.2.8",
  "dompurify": "^3.4.16"
}

---

3. Build Orchestration & Turborepo Caching (turbo.json)

Debelu integrates Turborepo to orchestrate dependency-aware build pipelines, topological task scheduling, and local/remote artifact caching.

// turbo.json
{
  "$schema": "https://turbo.build/schema.json",
  "tasks": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**", "build/**"]
    },
    "type-check": {
      "dependsOn": ["^build"],
      "outputs": []
    },
    "lint": {
      "outputs": []
    },
    "test": {
      "outputs": ["coverage/**"],
      "cache": false
    }
  }
}

3.1 Turbo Execution Commands

# Execute parallel builds with dependency graph hashing
npm run build:turbo

# Execute cached incremental type checking
npm run type-check:turbo

• Topological Sorting (^build): Turbo ensures that @debelu/core and @debelu/ui complete their build and type-checking tasks before downstream applications (apps/storefront, debelu-marketing) begin compiling.
• Cache Invalidation: Builds are automatically invalidated when source files within the workspace change or when package.json dependencies are altered.

---

4. Shared Package Standards & Architectural Invariants

4.1 @debelu/ui Design System Invariants

• Design Tokens: All colors, typography, border radiuses, and shadows originate exclusively from packages/ui/src/theme.css.
• Zero Ad-Hoc Styling: Applications must never introduce arbitrary hex colors (#1a2b3c) or custom CSS utility overrides. All visual components must be imported from @debelu/ui.
• Accessibility Guarantee: Interactive UI elements wrap @radix-ui primitives, ensuring keyboard navigation, focus trap compliance, and screen-reader accessibility.

4.2 @debelu/core Domain Services & Types

• Single Source of Truth: All domain interfaces (Order, UserProfile, VendorStore, Transaction, PayoutBatch) reside in packages/core/src/types.ts (~44 KB).
• Client Services: Stateless API clients (userService, paymentService, geminiService, notificationService) wrap native fetch with automatic JWT injection, retry policies, and RFC 7807 error parsing.

---

5. TypeScript Configuration & Project References

Debelu configures strict compiler checks at the monorepo root via [tsconfig.base.json](file:///c:/Users/frank/OneDrive/Desktop/Chisom/Debelu/New%20Debelu%20Marketplace/tsconfig.base.json), extended by workspace-specific tsconfig.json files:

// tsconfig.base.json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true,
    "noUncheckedIndexedAccess": true,
    "useUnknownInCatchVariables": true,
    "verbatimModuleSyntax": true,
    "erasableSyntaxOnly": true,
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@debelu/core": ["./packages/core/src/index.ts"],
      "@debelu/ui": ["./packages/ui/src/index.ts"]
    }
  }
}

5.1 Critical Compiler Invariants

1. noUncheckedIndexedAccess: true: Accessing array elements (arr[0]) or dictionary records (dict[key]) forces explicit undefined checks (T | undefined).
2. verbatimModuleSyntax: true: Types must be imported using explicit import type { Foo } from '...' syntax, eliminating runtime type leakage in bundlers.
3. strictNullChecks: true: Eliminates unintended null / undefined dereferences at compile time.

---

6. End-to-End Developer Workflows

sequenceDiagram
    autonumber
    participant Dev as Developer
    participant UI as packages/ui
    participant Core as packages/core
    participant Backend as debelu-backend
    participant App as apps/storefront

    Note over Dev,UI: Scenario A: Adding a Shared UI Component
    Dev->>UI: Creates packages/ui/src/components/CampusBadge.tsx
    Dev->>UI: Exports CampusBadge from packages/ui/src/index.ts
    Dev->>App: Imports <CampusBadge /> directly in Storefront View

    Note over Dev,Core: Scenario B: Adding a Shared Domain Service
    Dev->>Core: Implements CampusHubService.ts in packages/core/src/services/
    Dev->>Core: Exports CampusHubService from packages/core/src/index.ts
    Dev->>App: Invokes CampusHubService.getHubs() with React Query

    Note over Dev,Backend: Scenario C: Adding a New Backend REST Endpoint
    Dev->>Backend: Defines Zod schema in src/validators/campusValidators.ts
    Dev->>Backend: Implements domain logic in src/services/CampusOperationsService.ts
    Dev->>Backend: Creates route handler in src/routes/campusOperationsRouter.ts
    Dev->>Backend: Mounts route in src/server.ts under /api/campus

6.1 Adding a Shared Component to @debelu/ui

1. Create the component in packages/ui/src/components/MyComponent.tsx.
2. Apply design tokens from packages/ui/src/theme.css via Tailwind classes.
3. Export the component and its prop types from packages/ui/src/index.ts.
4. Run npm run type-check --workspace=@debelu/ui to confirm clean typing.

6.2 Adding a Shared Type or Service to @debelu/core

1. Define the interface or Zod validator in packages/core/src/types.ts or packages/core/src/schemas/.
2. Implement the client service in packages/core/src/services/MyService.ts.
3. Export from packages/core/src/index.ts.
4. Upstream apps immediately inherit typed auto-completion without re-compilation.

---

7. Pre-Push Verification Checklist

Before pushing any branch or opening a pull request, run the master monorepo validation suite:

# Execute complete verification: type-check + lint + unit tests + builds
npm run check

The npm run check pipeline validates four sequential gates:

1. Type Check: Zero TypeScript errors across all workspaces (npm run type-check).
2. Lint: Zero ESLint rule violations (npm run lint).
3. Unit Tests: 100% pass rate across workspace tests and Supabase edge functions (npm test).
4. Production Build: Successful compilation of distribution bundles for backend, storefront, and marketing applications (npm run build).

---

8. Document Revision History

Revision	Date	Lead Author	Scope of Changes	Status
1.0.0	2026-10-05	Principal Staff Engineer	Initial enterprise monorepo workflow specification detailing npm workspaces, Turborepo caching, shared package invariants, TypeScript configuration, and pre-push gates.	Active Living Standard