Skip to main content

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Development Commands​

Development Environment​

# Start all services (recommended)
./for-env local ./dev

# Individual services (if needed)
./for-env local npx sst dev       # Backend infrastructure
./for-env local pnpm dev          # Frontend client
./for-env local pnpm --filter subscriber-fanout dev  # WebSocket service

# Fast development mode with optimizations
pnpm dev-fast

Testing & Quality​

# Type checking across all packages
pnpm typecheck

# Linting
pnpm lint
pnpm lint:md        # Markdown files
pnpm lint:md:fix    # Auto-fix markdown issues

# Testing
pnpm test           # Run tests across all packages

Database Operations​

# Database migrations
./for-env local pnpm migrate up

# Seed database with initial data
./for-env local pnpm migrate seed

# Create a new user
pnpm db:create-user --profile bike4mind-dev

# Access MongoDB directly
./mongo

Documentation & Insights​

# Start documentation site
pnpm techdocs

# Generate analytics reports
pnpm daily-insights:generate
pnpm weekly-insights:generate

Architecture Overview​

Technology Stack​

  • Frontend: Next.js 14 with JOY UI (MUI's Joy UI - NOT Material UI)
  • Backend: AWS Lambda via SST (Serverless Stack)
  • Database: MongoDB with Mongoose ODM
  • State Management: Zustand + React Context + TanStack Query
  • Authentication: JWT with multi-provider OAuth
  • Infrastructure: AWS (Bedrock, S3, SQS, EventBridge, CloudFront)

Monorepo Structure​

Core Packages:

  • b4m-core/packages/core/ - Shared business logic, models, and services
  • packages/client/ - Next.js frontend and API routes
  • packages/subscriber-fanout/ - Real-time WebSocket service (Docker/ECS)
  • packages/scripts/ - Database migrations and utilities

Key Submodule: b4m-core is a git submodule containing core functionality shared across projects.

API Architecture​

File-based API Routes (packages/client/pages/api/):

  • Follow Next.js routing conventions
  • Use baseApi() wrapper for consistent middleware
  • Implement proper error handling with asyncHandler
  • Use repository pattern from b4m-core packages

Infrastructure via SST (sst.config.ts):

  • Lambda functions for API endpoints
  • SQS queues for async processing
  • WebSocket API for real-time features
  • S3 buckets for file storage with processing pipelines

Core Domain Models​

  • UserModel - User accounts and authentication
  • SessionModel - AI conversation sessions
  • QuestModel - AI task execution tracking
  • AgentModel - AI agent configurations
  • OrganizationModel - Multi-tenant organizations
  • FabFileModel - User files with processing metadata
  • MementoModel - Knowledge base entries
  • ArtifactModel - Dynamic UI components

AI & Processing Infrastructure​

Multi-LLM Support:

  • OpenAI GPT-4, Anthropic Claude, Amazon Bedrock, Google Gemini
  • Model routing through b4m-core/utils/llm backend system
  • Support for tools, vision, and streaming

Queue-Based Processing:

  • questStartQueue (10min) - AI quest execution
  • imageGenerationQueue (10min) - Bedrock image generation
  • fabFileChunkQueue (13min) - Document processing
  • fabFileVectQueue (5min) - Vector embeddings
  • notebookSummarizationQueue (2min) - Content summarization

Model Context Protocol (MCP):

  • Tool calling interface via Lambda functions
  • Dynamic tool discovery and execution
  • Located in b4m-core/packages/core/mcp/

Real-time Features​

WebSocket API:

  • Connection management ($connect, $disconnect, heartbeat)
  • Data subscriptions (subscribe_query, unsubscribe_query)
  • Voice agent routes for real-time AI voice interactions
  • Quest progress updates and notifications

Subscriber Fanout Service:

  • MongoDB change streams for real-time database updates
  • Efficient WebSocket message broadcasting to connected clients
  • Runs as Docker container on ECS Fargate

Authentication & Authorization​

Multi-Provider OAuth: Google, GitHub, Okta Authorization: CASL-based attribute access control with user scoping API Security: JWT tokens, API key management, request rate limiting

Development Patterns​

Component Architecture​

  • Use JOY UI components (NOT Material UI)
  • Separate components into presentation, state, and API layers
  • Use hooks for logic encapsulation
  • Implement error boundaries for auth-dependent components

Data Flow​

  • API calls via useApi hook (includes auth tokens)
  • TanStack Query for data fetching and caching
  • Zustand for client-side state management
  • Context providers for shared application state

Error Handling​

  • Custom error classes in b4m-core/common
  • Structured HTTP responses with proper status codes
  • Comprehensive logging to CloudWatch and Slack
  • Graceful UI fallbacks with user feedback

Type Safety​

  • Strict TypeScript across all packages
  • Zod schemas for runtime validation
  • Shared types in b4m-core/common
  • Workspace references for package dependencies

File Locations​

Adding New API Routes​

Add to packages/client/pages/api/ following Next.js conventions, then reference in sst.config.ts if special processing is needed.

Core Business Logic​

Implement in b4m-core/packages/core/ with proper separation:

  • common/ - Shared types, schemas, utilities
  • database/ - Mongoose models and database utilities
  • services/ - Pure domain services and repositories
  • utils/ - Cross-cutting concerns (logging, queues, etc.)

Frontend Components​

  • packages/client/app/components/ - Reusable UI components
  • Use the ProviderBundle context tree for authenticated features
  • Follow existing patterns for modal management and state

Queue Handlers​

Async processing handlers in packages/client/server/queueHandlers/ with corresponding queue definitions in sst.config.ts.

Important Notes​

  • Always use pnpm for package management
  • Use workspace references (workspace:*) for internal dependencies
  • The b4m-core submodule requires separate git commits when updated
  • AWS credentials managed via SSO - use ./for-env local wrapper
  • Environment-specific secrets managed through SST secrets
  • All components should work within the authentication provider tree