Skip to main content

Development Best Practices

All Bike4Mind developers are expected to adhere to a clear set of development practices that promote consistency, maintainability, and security across the platform. These practices apply to feature development, bug fixes, infrastructure changes, and refactors.

API and Middleware​

  • Always wrap API routes with the baseApi() middleware to ensure:

    • Database connection
    • User authentication
    • Permission context (req.ability)
    • Error handling and logging

  • Input validation must be performed using Zod schemas before processing payloads.

  • Do not bypass authentication or permissions, even for internal-only endpoints.

Authorization and Permissions​

  • Use CASL to enforce permissions across both client and server logic.

  • On the server, always use:

    if (!req.ability.can('action', resource)) throw new ForbiddenError();

  • On the client, use useAbility() to conditionally render components based on permissions.

  • Never assume role or resource ownership implicitly; enforce access explicitly.

Input Validation​

  • Use Zod schemas to validate all incoming data:

    • API requests (req.body, req.query, req.params)
    • Form submissions and client-side data

  • Use secureParameters() to parse and safely extract validated input.

  • Do not rely on client-side validation alone.

Authentication and Security​

  • Store tokens securely; never persist sensitive data in local storage unless encrypted and justified.
  • Never expose internal error messages, stack traces, or raw exception objects in production.
  • Use short-lived access tokens and rotate refresh tokens according to platform standards.
  • Review and audit use of secrets and environment variables. All sensitive values must be managed through SST.

Code Structure and Naming​

  • Favor clarity over cleverness in naming and structure.
  • Organize modules by domain, not technical function (e.g., notebooks/, not utils/)
  • Separate API handlers, validation schemas, types, and shared constants.
  • Avoid duplicate business logic across client and server—prefer shared utilities in b4m-core.

Git and Pull Requests​

  • All code changes must go through pull requests.

  • Pull requests should be:

    • Reviewed by at least one peer before merging
    • Linked to a GitHub issue for traceability
    • Accompanied by tests or validation evidence

  • Use preview deployments to validate behavior when possible.

Testing​

  • Write unit tests for core logic and business rules.
  • Validate edge cases and expected failures (e.g. permission denials, input rejections).
  • Regression bugs should always result in a test that prevents recurrence.
  • Manual testing should be accompanied by a Loom video or detailed reproduction steps.

Deployment Readiness​

  • Ensure feature toggles or fallback states exist for any partially released feature.
  • Confirm rollback safety prior to merging major changes.
  • Monitor error and telemetry dashboards after deploying to production.
  • Perform post-deploy validation in staging environments where applicable.

Documentation​

  • All new modules, APIs, or shared utilities must include inline documentation and an updated README.
  • Document non-obvious logic or architectural decisions in code comments or shared Notebooks.
  • Use Loom walkthroughs for complex flows or behavioral changes that are not self-evident.

These standards ensure that the platform remains stable, secure, and scalable as development accelerates. All developers are expected to internalize and apply these practices as part of their daily workflows.