Skip to main content

Bike4Mind – Developer Documentation

This documentation is intended for full-stack developers, QA engineers, DevOps teams, and internal engineering stakeholders working with or contributing to the Bike4Mind platform.

1. Platform Architecture​

  • Modular monorepo structure using TypeScript
  • Core stack: React (Next.js), Node.js, MongoDB, AWS (via SST)
  • Uses Serverless-first design with CI/CD managed via SEED
  • Code organized into:
    • b4m-core: shared business logic
    • packages/client: front-end app
    • packages/server: API routes and integrations

2. Authentication & Authorization​

  • Supports OAuth strategies: Google, GitHub, Okta (SAML/OIDC)
  • Stateless JWT-based auth system (access & refresh tokens)
  • Authentication flow handled in middleware (baseApi)
  • Authorization powered by CASL:
    • Role- and resource-based permissions
    • Supports user-level, shared, group, and global access patterns
    • Abilities scoped per request with req.ability.can()

3. Security Practices​

  • API inputs validated using Zod
  • Consistent error handling via asyncHandler
  • CORS rules restricted to known domains, configurable per environment
  • Secrets and environment variables managed via SST Secrets
  • Security checks include:
    • Least privilege permissions
    • No sensitive data in responses
    • Full JWT lifecycle handling (expiry, refresh, validation)
  • Regular security testing checklist:
    • Authentication bypass
    • Authorization bypass
    • Input validation failures
    • Token misuse
    • Error message leakage

4. API Structure & Middleware​

  • All API routes use a common baseApi() pattern
  • Core middleware responsibilities:
    • DB connection
    • JWT authentication
    • Authorization setup
    • Unified error handling
  • Permissions enforced per route via req.ability.can(action, resource)

5. DevOps, CI/CD, and Testing​

  • Infrastructure via SST with full AWS integration (Lambda, S3, RDS, CloudWatch)
  • CI/CD managed via SEED:
    • Automated builds, tests, deployment
    • One-click rollback
  • Local parity dev environments for all developers
  • Testing practices:
    • Unit tests (expanding)
    • Manual regression + QA pairing
    • Loom videos for complex scenarios

6. Telemetry & Observability​

  • 40+ telemetry points tracked across all deployments
  • Built-in dashboards monitor:
    • API performance
    • User/device/browser insights
    • Feature usage
  • Reports include:
    • Daily & weekly summaries via Slack/email
    • genAI-generated TL;DR insights
  • AWS X-Ray + CloudWatch used for tracing and log analysis

7. Developer Tools & Utilities​

  • Shared component libraries and design tokens
  • Utilities include:
    • secureParameters() for safe input handling
    • Zod schema validation
    • Unified type definitions across backend and frontend
  • Documentation practices:
    • Markdown READMEs in code
    • Slack-indexed internal docs
    • Loom video walkthroughs

8. Operational & Incident Response​

  • Runbooks documented in GitHub and internal systems
  • Incident playbooks define:
    • Issue classification (P0–P3)
    • Escalation paths
    • Rollback procedures (via SEED)
  • Slack and email used for real-time alerting
  • Post-mortems conducted after major incidents

9. Collaboration & Communication​

  • Teams based in Austin, Cebu, and Kyiv
  • Tools used:
    • Slack (daily ops + support)
    • GitHub Projects (task + issue tracking)
    • Loom (async status + demo sharing)
  • Agile ceremonies:
    • Sprint planning
    • Daily standups
    • Retrospectives (bi-weekly)
    • Pre/post-mortems

10. Development Best Practices​

Best Practices
  • ✅ Use baseApi() for all API routes
  • ✅ Validate all inputs with Zod
  • ✅ Use req.ability.can() to enforce permissions
  • ✅ Keep secrets out of client code
  • ✅ Follow the principle of least privilege
  • ✅ Review new features against the security checklist
danger
  • Never skip permission checks
  • Never expose internal error messages to clients

This guide ensures internal developers uphold consistent practices, security standards, and effective collaboration across the Bike4Mind platform.