Skip to content

phoenixvc/chaufher

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

207 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

ChaufHER Workspace — Platform Coordination Hub

The unified entry point for development, operations, and governance across the ChaufHER platform. Orchestrates cross-package coordination, enforces engineering standards, and streamlines safe delivery of features.

Monorepo: This is the ChaufHER monorepo containing all platform code — applications (apps/), infrastructure (infra/), shared packages (packages/), and documentation (docs/).

Phase Alignment: Phase 1 (MVP) delivers the React PWA + admin dashboard + .NET backend. Phase 2+ introduces a Flutter native mobile app. See Product Roadmap for the full phase breakdown.


Table of Contents

Product Documentation

Business & Product

Architecture & Design

Operations

Developer Guide

Reference


Product Documentation

Product Requirements

The Product Requirements Document (PRD) defines ChaufHER's vision, goals, and scope:

  • Mission: A ride-hail platform designed for women, providing scheduled rides with vetted female drivers
  • MVP Focus: Scheduled rides only (on-demand is future scope)
  • Core Features: Ride scheduling, driver profiles, status notifications, secure payments
  • Target Metrics: 1,000+ rides in 3 months, 100+ active drivers, 4.8+ CSAT score

Read the full PRD: docs/01_product/01_prd.md

Functional Specification

The Functional Specification (Schedule 3) provides detailed implementation requirements:

  • 19 Feature Areas: Authentication, Rider/Driver flows, Admin dashboard, Payments, Notifications, and more
  • Acceptance Criteria: Specific validation rules, integration behaviors, and screen lists for each feature
  • Status Tracking: Current implementation status (Completed, UAT, Blocked) with due dates
  • Integration Behaviors: Detailed specifications for third-party integrations and system interactions
Status Count Features
Completed 4 Backend API, Analytics, Security, Infrastructure
UAT 12 Auth, Driver Portal, Notifications, Real-Time, Maps, PWA, Database, Driver Verification, Testing, Ops Docs, Pilot Prep, Post-Launch
Blocked 3 Rider Experience, Admin Dashboard, Payment Integration

Read the full specification: docs/02_specs/01_functional_spec.md

Review gaps and discrepancies: docs/14_governance/03_spec_comparison.md

User Personas & Customer Journey

ChaufHER serves six core personas across riders, drivers, and administrators:

Persona Role Primary Need
Sarah Corporate Guardian Safe child transport logistics
Nomsa Community Driver Flexible income with safety
Aisha Solo Commuter Reliable late-shift transport
Thandi School Admin Group transport efficiency
Zanele Young Professional Digital-first, transparent service
Lerato Family Advocate Multi-household coordination

The Customer Journey Map details the full experience across five stages:

  1. Awareness — Discovery via referrals, social media, school/corporate channels
  2. Consideration — Evaluating safety protocols, driver vetting, testimonials
  3. Decision — Onboarding, registration, first ride setup
  4. Retention — Regular bookings, recurring schedules, live tracking
  5. Advocacy — Referrals, community participation, feedback

Read more: User Personas | Customer Journey Map

Design Guardrails

The Design Guardrails define non-negotiable UX principles:

Guardrail Principle
Safety First Safety signals must be visible and concrete, not implied
Status Clarity Users must always know "what is happening now" and "what happens next"
Predictability Simple, predictable rules beat many configuration options
Human Fallback Clear paths to human help in all critical states
Repetition-Ready Flows optimized for recurring patterns (school runs, shifts)

Read the full guardrails: docs/02_specs/03_design_guardrails.md


Business & Product

Product Overview

ChaufHER Workspace is the orchestration hub for the entire ChaufHER platform, bringing together mobile, backend, web, and infrastructure codebases into a unified, coordinated development environment.

Core Value Proposition

  • Single Source of Truth: Centralized documentation, policies, and standards
  • Rapid Onboarding: Streamlined setup for new contributors across all repos
  • Coordinated Delivery: Synchronized releases and environment promotions
  • Governance Enforcement: Automated policy checks and compliance validation
  • Operational Excellence: Unified CI/CD, monitoring, and incident response

Key Capabilities

Capability Description Benefit
Shared Documentation Centralized guides, policies, standards Consistent knowledge base
CI/CD Orchestration Cross-repo pipeline coordination Synchronized releases
Environment Management Dev/staging/prod promotion workflows Controlled deployments
Policy Enforcement Automated security, compliance checks Risk mitigation
Onboarding Automation Standardized setup procedures Faster productivity
Incident Coordination Unified runbooks, escalation paths Rapid response

Purpose & Value

Business Problems Solved

  1. Onboarding Friction: New engineers productive in hours, not weeks
  2. Configuration Drift: Synchronized policies prevent inconsistencies
  3. Release Coordination: Atomic multi-repo deployments reduce failures
  4. Compliance Burden: Automated audits simplify regulatory requirements
  5. Knowledge Silos: Centralized documentation eliminates tribal knowledge

Technical Challenges Addressed

  1. Multi-Repo Complexity: Orchestrated workflows manage dependencies
  2. Environment Parity: Consistent configs across dev/staging/prod
  3. Secret Management: Centralized Key Vault with automated rotation
  4. Policy Enforcement: Automated checks prevent non-compliant merges
  5. Incident Response: Standardized runbooks enable rapid recovery

Example Scenarios

Scenario 1: New Engineer Onboarding

  • Engineer joins team, follows Workspace onboarding guide
  • Automated scripts configure local environments for all repos
  • Pre-commit hooks enforce code standards
  • First PR merged within 24 hours

Scenario 2: Coordinated Release

  • Product team requests feature deployment
  • Workspace orchestrates builds across app, api, web repos
  • Automated tests validate cross-repo compatibility
  • Staged rollout to staging, then production
  • Release notes auto-generated and published

Scenario 3: Security Policy Update

  • Security team updates secrets-handling policy
  • Workspace CI enforces new policy across all repos
  • Non-compliant PRs automatically blocked
  • Audit trail generated for compliance review

Target Audience

Primary Users

Engineers

  • Role: Develop features, fix bugs, maintain code quality
  • Needs: Standardized setup, clear guidelines, reliable CI/CD
  • Pain Points: Inconsistent environments, unclear standards

DevOps/SRE

  • Role: Orchestrate deployments, monitor systems, respond to incidents
  • Needs: Runbooks, automation tools, observability dashboards
  • Pain Points: Manual deployments, fragmented monitoring

Secondary Users

Product/Engineering Managers

  • Role: Track delivery, assess team productivity, plan capacity
  • Needs: Metrics dashboards, release cadence visibility
  • Tools: GitHub Insights, custom dashboards

Security/Compliance Teams

  • Role: Audit adherence, enforce policies, assess risk
  • Needs: Automated compliance reports, audit trails
  • Tools: Policy scan results, secrets audit logs

Leadership

  • Role: Strategic oversight, risk assessment, resource allocation
  • Needs: Platform reliability metrics, incident summaries
  • Tools: Executive dashboards, quarterly reports

Expected Outcomes

Business Impact

Short-Term (0-6 months):

  • Reduced onboarding time (target: <4 hours)
  • Faster release cadence (target: daily deploys)
  • Fewer deployment failures (target: <5%)
  • Improved developer satisfaction

Long-Term (6-24 months):

  • Full audit compliance (SOC 2, ISO 27001)
  • Predictable delivery timelines
  • Reduced incident recovery time
  • Scalable engineering processes

Key Performance Indicators

Metric Target Measurement Owner
Median Onboarding Time <4 hours Time to first PR Engineering Manager
Change Lead Time <24 hours Code to production DevOps Lead
Deployment Success Rate >95% Successful deploys Platform Lead
Incident Recovery Time <30 min MTTR for P1 incidents SRE Lead
Policy Compliance 100% Automated scan pass rate Security Lead
Developer Satisfaction >80% Quarterly survey NPS Engineering Manager

Architecture & Design

Monorepo Architecture

ChaufHER is a monorepo containing all platform code, coordinated via Nx workspace tooling:

chaufher/                        (monorepo root — this repo)
├── apps/
│   ├── pwa/                     React PWA client (Phase 1)
│   ├── admin/                   React admin dashboard (Phase 1)
│   ├── api/                     .NET 9 backend (all phases)
│   └── docs/                    Docusaurus documentation site
├── infra/                       Azure IaC — Bicep/Terraform (all phases)
│   ├── bicep/
│   ├── terraform/
│   └── terragrunt/
├── packages/                    Shared packages
│   ├── config/                  Shared configuration
│   ├── types/                   Shared TypeScript types
│   ├── ui/                      Shared UI components
│   └── utils/                   Shared utilities
├── docs/                        Core documentation
│   ├── app/                     App technical designs (PWA + Flutter)
│   ├── web/                     Web/admin technical design
│   ├── infra/                   Infrastructure technical design
│   └── product-roadmap.md       Phased product roadmap
├── adr/                         Architecture Decision Records
├── scripts/                     Automation scripts
└── .github/                     CI/CD pipeline definitions

Package Responsibilities

Package Purpose Technology Phase
apps/pwa/ Client PWA for riders/drivers React/Next.js/TypeScript Phase 1
apps/admin/ Admin portal, operations dashboard React/TypeScript Phase 1
apps/api/ Backend services, business logic .NET 9, PostgreSQL All phases
apps/docs/ Documentation site Docusaurus All phases
infra/ Infrastructure as code, provisioning Bicep/Terraform All phases
packages/ Shared config, types, UI, utilities TypeScript All phases

Why PWA? See ADR-001: Client Technology Selection for the weighted evaluation of Flutter, React Native, Native, and PWA approaches. Flutter native mobile app is planned for Phase 2+. See Flutter Technical Design.

Package Boundaries

  • Autonomy: Each package maintains local development independence
  • Coordination: Nx workspace orchestrates builds, tests, and deployments
  • Ownership: Teams mapped by package, reviewers tracked per area
  • Integration: GitHub Actions with shared workflow templates

Design Philosophy

Core Principles

1. Single Source of Truth

  • All shared documentation lives in Workspace
  • Policies defined once, enforced everywhere
  • No duplicate or conflicting standards

2. Automation First

  • Manual processes are technical debt
  • CI/CD handles repetitive tasks
  • Policy enforcement automated via checks

3. Safety by Default

  • Breaking changes blocked automatically
  • Secrets never in source code
  • All deployments reversible

4. Auditability

  • Every action logged with timestamp
  • Compliance reports auto-generated
  • Incident timelines traceable

5. Developer Experience

  • Fast feedback loops (CI <10 min)
  • Clear error messages
  • Self-service documentation

Design Patterns

Pattern Usage Benefit
Event-Driven Pipelines GitHub Actions triggers Parallel execution, fast feedback
Layered Environments Dev → Staging → Prod Controlled rollout, risk mitigation
DRY Policy Enforcement Shared YAML templates Consistency, maintainability
Semantic Versioning Release tagging Clear compatibility signals
Feature Flags Staged rollouts Safe experimentation

Cross-Package Coordination

Environment Promotion

Coordinated promotion across all packages via CI/CD workflows:

Development → Staging → Production
     ↓            ↓           ↓
  Auto-deploy  Validation  Manual approval

Promotion Workflow:

  1. Tag release in Workspace (release/v1.2.3)
  2. Trigger builds across all repos
  3. Run cross-repo integration tests
  4. Deploy to staging environment
  5. Automated smoke tests + manual validation
  6. Approval gate (product + ops sign-off)
  7. Canary deploy to production (10% → 50% → 100%)
  8. Monitor metrics, auto-rollback on errors
  9. Generate and publish release notes

Secrets Management

  • Centralized: Azure Key Vault per environment
  • Automated Rotation: Every 90 days
  • Access Control: Managed identities, least-privilege
  • Audit Trail: All access logged

Version Gating

  • PR Checks: Cross-repo compatibility validated
  • Semantic Versioning: Major.Minor.Patch enforced
  • Breaking Changes: Require major version bump
  • Deprecation Policy: 3 months notice before removal

Compliance Triggers

Automated checks before merge:

  • License scanning (FOSSA, Black Duck)
  • Secrets detection (Gitleaks, TruffleHog)
  • Dependency vulnerabilities (Dependabot, Snyk)
  • Policy compliance (custom checks)

System Interfaces

Internal APIs

  • REST/GraphQL: App/web to API communication
  • SignalR: Real-time updates (WebSocket)
  • OpenAPI: Centralized API documentation

Third-Party Integrations

Service Purpose Protocol
GitHub Actions, Checks, Releases REST API, Webhooks
Azure Key Vault Secrets management HTTPS, OAuth
Slack/Teams Alerts, incident comms Webhooks, REST API
Sentry Error tracking HTTPS, SDK
Application Insights Monitoring, metrics HTTPS, SDK

Authentication

  • OAuth/OpenID: User authentication
  • Managed Identities: Service-to-service auth
  • JWT Tokens: API authentication

Operations

Deployment

Deployment Environments

Environment Purpose Infrastructure Data
Development Feature development Local/cloud hybrid Synthetic
Staging Pre-production validation Mirrors production Scrubbed prod copy
Production Live customer traffic Multi-AZ, auto-scaling Real customer data

Deployment Tools

  • Orchestrator: GitHub Actions
  • IaC: Terraform/Bicep (infra repo)
  • Containers: Docker, Kubernetes with Helm
  • Secrets: Azure Key Vault integration

Deployment Steps

  1. Tag Release: Push release/* tag in Workspace
  2. Trigger Orchestration: Workspace workflow launches per-repo builds
  3. Run Validations: Cross-repo E2E, contract, secrets checks
  4. Promote to Staging: Deploy all repos to staging
  5. Stakeholder Review: Automated + manual sign-off
  6. Promote to Production: Canary rollout with monitoring
  7. Monitor & Rollback: Auto-rollback on failure
  8. Publish Release Notes: Changelog to docs and Slack

Post-Deployment Verification

  • Health Checks: Automated endpoint validation
  • Secrets Check: Ensure no credential exposure
  • Monitoring: Sentry/Application Insights integration
  • Audit Logs: All actions logged for compliance

Testing & Quality

Test Strategy

Test Type Scope Tools Frequency
E2E Cross-repo user workflows Cypress, Playwright Every PR
Contract API compatibility Postman, Newman Every PR
Integration Service boundaries Jest, pytest Every PR
Security Secrets, vulnerabilities Gitleaks, Snyk Every commit
Compliance Policy adherence Checkov, custom Every PR
DR Drills Disaster recovery Manual + automated Quarterly

Testing Environments

  • Sandbox: PR validations, onboarding walkthroughs
  • Staging: Pre-release validation, mirrors production
  • Production: Canary deploys, monitored rollouts

Test Cases

Test Case Description Expected Outcome
App E2E Login Validate user sign-in/sign-up Consistent success/error handling
API Contract Test breaking changes Zero incompatible changes
Secrets Rotation Simulate key rotation No disruption, alerts as expected
DR Drill Trigger failover Full recovery in SLA timeframe

Metrics & Reporting

Tracked Metrics:

  • E2E suite pass/fail rate
  • API contract change failures
  • DR drill recovery times
  • Secrets scan incidents

Reporting:

  • Automated dashboards (GitHub, Grafana)
  • Scheduled reports to Slack/Teams
  • Stakeholder summaries for releases

Contact & Support

Team

Name Role Email
Jurie Primary Contact jurie@phoenixvc.tech
Eben Secondary Contact eben@phoenixvc.tech

Getting Help

For questions, issues, or support:


Developer Guide

Quick Start

Prerequisites

  • Git, Node.js 18+, .NET 9 SDK
  • Docker (optional for local services)
  • Azure CLI (for Key Vault access)

Initial Setup

  1. Clone Workspace
  2. Run Setup Script
  3. Configure Environments
  4. Verify Setup

Local Development

Start all services:

Individual repos:

  • See repo-specific READMEs for detailed setup
  • All repos follow consistent structure

Development Guidelines

Naming Conventions

Element Convention Example
Branches feature/, fix/, chore/ feature/panic-button
Commits Conventional commits feat(auth): add JWT refresh
Tags Semantic versioning v1.2.3
Workflows kebab-case cross-repo-promotion.yml

Commit Conventions

<type>(<scope>): <subject>

<body>

<footer>

Types: feat, fix, refactor, test, docs, chore

Examples:

  • feat(workspace): add cross-repo promotion workflow
  • fix(ci): resolve secrets rotation script timeout
  • docs(readme): update onboarding checklist

Git Workflow

Branching Strategy:

  • main — Production-ready
  • feature/* — Feature branches
  • fix/* — Bugfix branches
  • release/* — Release preparation

Pull Request Process:

  1. Create feature branch from main
  2. Push and open PR with description
  3. All checks must pass (tests, linters, policy)
  4. Await code review approval
  5. Squash and merge on approval
  6. Delete branch after merge

Code Quality Standards

  • Linting: Enforced per repo (ESLint, Prettier, etc.)
  • Testing: Minimum 80% coverage for critical paths
  • Security: No secrets in code, automated scans
  • Documentation: Update docs with code changes

Contributing

Before You Commit

  • Code follows naming conventions
  • All tests pass locally
  • Linting passes
  • No secrets in commit
  • Commit message follows convention
  • Documentation updated
  • Branch up-to-date with main

Pull Request Checklist

  • PR description explains changes
  • Related issues linked
  • Breaking changes documented
  • Tests added/updated
  • CI checks passing
  • Reviewers assigned

Review Process

  1. Automated checks run (CI/CD)
  2. Code review by team member
  3. Address feedback, re-request review
  4. Approval required before merge
  5. Squash and merge to main

Reference

Documentation Index

Product & Design

Technical Architecture

  • System Architecture — High-level system architecture, data flows, component diagrams
  • C4 Diagrams — Context, Container, Component, and Code level architecture diagrams
  • Data Model — Entity Relationship Diagram, database schema, field definitions
  • API Reference — REST API endpoints, request/response examples, WebSocket events
  • CODER Evaluations — Cost, Operational, Developer, Extensibility, Risk assessments for all ADRs

Stakeholder Decisions

Recommendation documents (all resolved):

Document Topics Status
REC-001: Critical Blockers Payment timing, password expiry, 3DS/CVV Resolved
REC-002: Payment & Billing Transaction limits, commission, payouts Resolved
REC-003: Driver Matching Response window, notifications, reminders Resolved
REC-004: User Experience Minimum age, clock format, stops, tipping Resolved
REC-005: Safety & Compliance SAFER integration, MasterDrive Resolved
REC-006: Operational Rules Booking notice, auto-logout, service areas Resolved

Developer Resources

  • Onboarding Guide — Day-by-day setup instructions, environment configuration, first contribution guide

Architecture Decision Records (ADRs)

All architectural decisions are documented with weighted evaluation matrices per ADR-000.

ADR Title Status Category
ADR-000 ADR Specification Proposed Process
ADR-001 Client Technology (PWA vs Flutter) Proposed Frontend
ADR-002 Database Technology (PostgreSQL) Proposed Data
ADR-003 Real-Time Communication (SignalR) Proposed Backend
ADR-004 Caching Strategy (Redis) Proposed Backend
ADR-005 Documentation Platform (Notion) Proposed Process
ADR-006 Team Communication (Slack) Proposed Process
ADR-007 Authentication (Azure AD B2C) Proposed Security
ADR-008 Cloud Provider (Azure) Proposed Infrastructure
ADR-009 Backend Framework (.NET 9) Proposed Backend
ADR-010 Infrastructure as Code (Bicep) Proposed Infrastructure
ADR-011 CI/CD Platform (GitHub Actions) Proposed DevOps
ADR-012 Project Management (Linear) Proposed Process
ADR-013 Monitoring & Observability (Azure Monitor) Proposed Operations
ADR-014 Payment Gateway (Peach Payments) Accepted Payments
ADR-015 SMS & Notifications (Africa's Talking) Proposed Communications
ADR-016 Maps & Geolocation (Google Maps) Proposed Integration
ADR-017 Background Jobs (Hangfire) Proposed Backend
ADR-018 Email Provider (SendGrid) Proposed Communications
ADR-019 File Storage (Azure Blob) Proposed Infrastructure
ADR-020 Error Tracking (Sentry) Accepted Operations
ADR-021 Feature Flags (Azure App Config) Proposed DevOps
ADR-022 Analytics & BI (Power BI) Proposed Analytics
ADR-023 Networking & API Gateway (Azure Front Door) Proposed Infrastructure
ADR-024 Security Architecture (Defense in Depth) Accepted Security
ADR-025 Disaster Recovery & HA (Zone Redundancy) Proposed Infrastructure
ADR-026 Driver Matching Algorithm Proposed Backend
ADR-027 Driver Scheduling Algorithm Proposed Backend
ADR-028 Container Runtime Proposed Infrastructure
ADR-029 Frontend State Management Proposed Frontend
ADR-030 API Versioning Proposed Backend
ADR-031 Safety & Panic (SAFER) Proposed Safety
ADR-032 WhatsApp Business API Proposed Communications
ADR-033 Push Notifications (FCM) Accepted Communications
ADR-034 Pricing & Fare Engine Accepted Backend
ADR-035 Requirements Traceability Accepted Governance
ADR-036 Platform Configuration Accepted Backend
ADR-037 Documentation Sync Accepted Tooling
ADR-038 Visualization Components Accepted Frontend
ADR-039 Project Planning Accepted Tooling
ADR-040 Comment/Feedback Integration Accepted Frontend

Package Documentation

Technical documentation for each package in the ChaufHER monorepo:

Package Documentation Description
apps/pwa docs/06_engineering/02_pwa_technical_design.md PWA technical design, architecture, development guide
apps/api docs/04_api/README.md .NET 9 backend, API endpoints, authentication
apps/admin docs/06_engineering/04_web_admin_design.md React admin portal, design variants, operations
infra docs/06_engineering/01_infra_design.md Azure infrastructure, Bicep modules, runbooks
Flutter docs/06_engineering/03_flutter_technical_design.md Flutter native mobile (Phase 2+)
Roadmap docs/01_product/02_product_roadmap.md Phased product roadmap (Phase 1–4)

Planned Documentation

Note: The following documents are planned for future development phases:

Quick Links (Planned)

  • Security Policy
  • CI/CD Pipeline Reference
  • Contribution Guidelines

Policies & Standards (Planned)

  • Secrets Management
  • Code Review Standards
  • Deployment Policy
  • Incident Response
  • Compliance Requirements

Runbooks (Planned)

  • Deployment Runbook
  • Rollback Procedures
  • Incident Response
  • DR Drill Procedures
  • Secrets Rotation

Repository

This is the ChaufHER monorepo containing all platform code.

Resource Link
chaufher (this repo) GitHub

License

Copyright (c) 2025 ChaufHER. All rights reserved.

[Add License Here — e.g., MIT, Apache 2.0, or proprietary]


ChaufHER Workspace delivers unified orchestration for safe, reliable, and auditable platform delivery.

About

No description, website, or topics provided.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Contributors 6