Skip to main content

Developer Tools & Utilities

Bike4Mind provides a suite of shared tools, libraries, and structured conventions to promote consistency, speed up development, and reduce the surface area for errors across the monorepo. These tools are used across both client and server code and form the foundation of the developer experience.

Shared Packages and Type Definitions​

  • All cross-cutting logic is organized within the b4m-core directory:

    • common/types: Platform-wide TypeScript definitions for entities such as users, permissions, notebooks, and authentication payloads
    • common/schemas: Input validation schemas using Zod
    • common/constants: Shared enums and static values for things like permissions, roles, and statuses

By colocating logic in b4m-core, duplication is avoided and all services share a canonical source of truth for domain rules.

Permission and Authorization Utilities​

  • CASL is the underlying authorization engine

  • A centralized defineAbilityFor(user) function returns the current user’s permissions for use in API routes or UI rendering

  • Backend checks follow the standard pattern:

    if (!req.ability.can('update', subject)) throw new ForbiddenError();

  • Frontend components use useAbility() to control UI-level access to features and actions

This design ensures consistent enforcement of access rules across the stack.

Base API Handler Pattern​

All backend routes use the baseApi() wrapper, which:

  • Verifies JWTs and authenticates the user
  • Initializes the permission system (CASL abilities)
  • Connects to the database
  • Applies global error handling
  • Attaches metadata for observability

This approach avoids code duplication and guarantees all API routes meet the platform’s security and logging requirements.

Input Validation​

All user input—whether from forms, API payloads, or query strings—is validated using Zod schemas. These schemas are:

  • Declared once and imported into both frontend and backend modules
  • Used to validate request parameters before processing
  • Co-located with the corresponding domain logic (e.g. schemas/notebook.ts)

The secureParameters() utility wraps Zod parsing to simplify and standardize extraction:

const data = secureParameters(req.body, notebookSchema);

UI Component and Styling System​

  • UI components are built using:

    • Tailwind CSS for consistent, responsive styling via utility classes
    • ShadCN UI for accessible, pre-built components extended to support Bike4Mind themes

  • Components follow clear design guidelines for spacing, alignment, interactivity, and responsiveness

  • Complex components (e.g. file uploaders, prompt editors) are implemented in the components directory and reused across pages

Internal Documentation​

  • Project-level READMEs are required for all modules under b4m-core

  • Developer onboarding and architectural overviews are maintained in:

    • GitHub markdown files
    • Indexed Slack references
    • Internal documentation Notebooks and Projects

  • Video walkthroughs (via Loom) are used to supplement written documentation and are required for all major refactors or feature launches

Local Development and CLI Tools​

  • Developers run the platform locally with parity to production environments

  • Common workflows (e.g. seed data, environment setup) are supported via:

    • Custom scripts in package.json
    • SST dev server and SEED preview deployments
    • .env.example files for secure configuration

Development environments are version-controlled, reproducible, and designed to mirror CI/CD behavior as closely as possible.

This developer tooling ecosystem ensures consistency, enforces platform constraints, and enables teams to build, test, and deploy new features with confidence.