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.
- Monorepo Architecture
- Design Philosophy
- Cross-Package Coordination
- System Interfaces
- Data Model
- API Reference
- C4 Diagrams
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
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
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:
- Awareness — Discovery via referrals, social media, school/corporate channels
- Consideration — Evaluating safety protocols, driver vetting, testimonials
- Decision — Onboarding, registration, first ride setup
- Retention — Regular bookings, recurring schedules, live tracking
- Advocacy — Referrals, community participation, feedback
Read more: User Personas | Customer Journey Map
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
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.
- 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
| 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 |
- Onboarding Friction: New engineers productive in hours, not weeks
- Configuration Drift: Synchronized policies prevent inconsistencies
- Release Coordination: Atomic multi-repo deployments reduce failures
- Compliance Burden: Automated audits simplify regulatory requirements
- Knowledge Silos: Centralized documentation eliminates tribal knowledge
- Multi-Repo Complexity: Orchestrated workflows manage dependencies
- Environment Parity: Consistent configs across dev/staging/prod
- Secret Management: Centralized Key Vault with automated rotation
- Policy Enforcement: Automated checks prevent non-compliant merges
- Incident Response: Standardized runbooks enable rapid recovery
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
- Role: Develop features, fix bugs, maintain code quality
- Needs: Standardized setup, clear guidelines, reliable CI/CD
- Pain Points: Inconsistent environments, unclear standards
- Role: Orchestrate deployments, monitor systems, respond to incidents
- Needs: Runbooks, automation tools, observability dashboards
- Pain Points: Manual deployments, fragmented monitoring
- Role: Track delivery, assess team productivity, plan capacity
- Needs: Metrics dashboards, release cadence visibility
- Tools: GitHub Insights, custom dashboards
- Role: Audit adherence, enforce policies, assess risk
- Needs: Automated compliance reports, audit trails
- Tools: Policy scan results, secrets audit logs
- Role: Strategic oversight, risk assessment, resource allocation
- Needs: Platform reliability metrics, incident summaries
- Tools: Executive dashboards, quarterly reports
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
| 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 |
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 | 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.
- 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
- All shared documentation lives in Workspace
- Policies defined once, enforced everywhere
- No duplicate or conflicting standards
- Manual processes are technical debt
- CI/CD handles repetitive tasks
- Policy enforcement automated via checks
- Breaking changes blocked automatically
- Secrets never in source code
- All deployments reversible
- Every action logged with timestamp
- Compliance reports auto-generated
- Incident timelines traceable
- Fast feedback loops (CI <10 min)
- Clear error messages
- Self-service documentation
| 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 |
Coordinated promotion across all packages via CI/CD workflows:
Development → Staging → Production
↓ ↓ ↓
Auto-deploy Validation Manual approval
Promotion Workflow:
- Tag release in Workspace (
release/v1.2.3) - Trigger builds across all repos
- Run cross-repo integration tests
- Deploy to staging environment
- Automated smoke tests + manual validation
- Approval gate (product + ops sign-off)
- Canary deploy to production (10% → 50% → 100%)
- Monitor metrics, auto-rollback on errors
- Generate and publish release notes
- Centralized: Azure Key Vault per environment
- Automated Rotation: Every 90 days
- Access Control: Managed identities, least-privilege
- Audit Trail: All access logged
- 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
Automated checks before merge:
- License scanning (FOSSA, Black Duck)
- Secrets detection (Gitleaks, TruffleHog)
- Dependency vulnerabilities (Dependabot, Snyk)
- Policy compliance (custom checks)
- REST/GraphQL: App/web to API communication
- SignalR: Real-time updates (WebSocket)
- OpenAPI: Centralized API documentation
| 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 |
- OAuth/OpenID: User authentication
- Managed Identities: Service-to-service auth
- JWT Tokens: API authentication
| 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 |
- Orchestrator: GitHub Actions
- IaC: Terraform/Bicep (infra repo)
- Containers: Docker, Kubernetes with Helm
- Secrets: Azure Key Vault integration
- Tag Release: Push
release/*tag in Workspace - Trigger Orchestration: Workspace workflow launches per-repo builds
- Run Validations: Cross-repo E2E, contract, secrets checks
- Promote to Staging: Deploy all repos to staging
- Stakeholder Review: Automated + manual sign-off
- Promote to Production: Canary rollout with monitoring
- Monitor & Rollback: Auto-rollback on failure
- Publish Release Notes: Changelog to docs and Slack
- Health Checks: Automated endpoint validation
- Secrets Check: Ensure no credential exposure
- Monitoring: Sentry/Application Insights integration
- Audit Logs: All actions logged for compliance
| 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 |
- Sandbox: PR validations, onboarding walkthroughs
- Staging: Pre-release validation, mirrors production
- Production: Canary deploys, monitored rollouts
| 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 |
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
| Name | Role | |
|---|---|---|
| Jurie | Primary Contact | jurie@phoenixvc.tech |
| Eben | Secondary Contact | eben@phoenixvc.tech |
For questions, issues, or support:
- Primary: jurie@phoenixvc.tech
- CC: eben@phoenixvc.tech
- GitHub Issues: Bug reports, feature requests
- Git, Node.js 18+, .NET 9 SDK
- Docker (optional for local services)
- Azure CLI (for Key Vault access)
- Clone Workspace
- Run Setup Script
- Configure Environments
- Verify Setup
Start all services:
Individual repos:
- See repo-specific READMEs for detailed setup
- All repos follow consistent structure
| 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 |
<type>(<scope>): <subject>
<body>
<footer>
Types: feat, fix, refactor, test, docs, chore
Examples:
feat(workspace): add cross-repo promotion workflowfix(ci): resolve secrets rotation script timeoutdocs(readme): update onboarding checklist
Branching Strategy:
main— Production-readyfeature/*— Feature branchesfix/*— Bugfix branchesrelease/*— Release preparation
Pull Request Process:
- Create feature branch from
main - Push and open PR with description
- All checks must pass (tests, linters, policy)
- Await code review approval
- Squash and merge on approval
- Delete branch after merge
- 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
- 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
- PR description explains changes
- Related issues linked
- Breaking changes documented
- Tests added/updated
- CI checks passing
- Reviewers assigned
- Automated checks run (CI/CD)
- Code review by team member
- Address feedback, re-request review
- Approval required before merge
- Squash and merge to
main
- Product Requirements Document (PRD) — Vision, goals, user stories, functional requirements
- Functional Specification — Detailed acceptance criteria, screen lists, validations, and integration behaviors (Schedule 3)
- Specification Comparison — Gap analysis comparing Functional Spec against PRD, ADRs, and design documents
- Open Decisions — Business decisions (all resolved)
- Documentation Audit — Inconsistencies, gaps, and missing documentation analysis
- Missing Documentation Tracker — Prioritized list of 46 documents needed for production
- Future Opportunities — Post-MVP features, expansion, and strategic opportunities
- User Personas — Detailed profiles of riders, drivers, and administrators
- Customer Journey Map — End-to-end experience across all touchpoints
- Design Guardrails — Non-negotiable UX principles
- 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
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 |
- Onboarding Guide — Day-by-day setup instructions, environment configuration, first contribution guide
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 |
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) |
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
This is the ChaufHER monorepo containing all platform code.
| Resource | Link |
|---|---|
| chaufher (this repo) | GitHub |
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.