This file provides high-level guidance to Claude Code (claude.ai/code) when working with the Flowshapr monorepo.
Flowshapr is a visual drag-and-drop interface for building Firebase Genkit AI flows. The system allows users to create, manage, and deploy AI flows to various platforms while providing a thin SDK for remote execution. It generates production-ready TypeScript code from visual flows and executes them in real-time.
This monorepo is organized into focused components with dedicated documentation:
genkit-builder/
├── frontend/ # Next.js visual flow builder
│ └── CLAUDE.md # → Frontend-specific guidance
├── server/ # Express.js API backend
│ └── CLAUDE.md # → Backend-specific guidance
├── sdk/ # Client SDK for flow execution
│ └── CLAUDE.md # → SDK-specific guidance
├── docker/ # Container configurations
├── scripts/ # Build and deployment scripts
├── testapps/ # Test applications
└── docs/ # Documentation
When working on specific parts of the system, refer to the component-specific CLAUDE.md files:
- Frontend Development - React Flow visual editor, Next.js patterns, UI components
- Backend Development - Domain-driven design, API architecture, database integration
- SDK Development - Client library, Genkit compatibility, TypeScript definitions
# Development
npm run dev # Start frontend development server
npm run build # Build all components
npm run lint --workspace=frontend # Lint specific workspace
npm run type-check --workspace=frontend # Type-check specific workspace
# Component-specific development
cd frontend && npm run dev # Frontend development
cd server && npm run dev # Backend development
cd sdk && npm run build # SDK development
# Database operations (server)
cd server && npm run db:migrate # Run database migrations
cd server && npm run db:studio # Open database GUI
# Testing
cd server && npm run test # Run backend tests
npm run testapps:all # Run integration tests
The system follows a modern three-tier architecture with clear separation of concerns:
- Visual Flow Builder: React Flow-based drag-and-drop interface
- Real-time Code Generation: Live TypeScript generation from visual flows
- Execution Interface: Flow testing and debugging UI
- Authentication: Session-based auth with social providers
- Domain-Driven Design: Clean architecture with focused business domains
- Unified Authentication: Laravel Sanctum-style session + token auth
- Flow Execution: Containerized Genkit flow execution
- Multi-tenancy: Organization and team-based access control
- Genkit Compatibility: Drop-in replacement for Genkit client
- Multiple Environments: Production, local, and custom instances
- Streaming Support: Real-time flow execution with SSE
- Type Safety: Full TypeScript support with generics
Visual Editor → Code Generation → Backend API → Container Execution → Results
↑ ↓
User UI ←── Real-time Updates ←── Traces & Logs
- Input Validation: Zod schemas across all layers
- Authorization: Service-level permissions with central abilities
- Code Execution: Isolated Docker containers with resource limits
- API Security: Rate limiting, CORS, and secure session management
- PostgreSQL: Primary database with Drizzle ORM
- Multi-tenancy: Organization → Teams → Users → Flows hierarchy
- Audit Trails: Execution traces and user activity logging
- Performance: Indexed queries and connection pooling
- Containerization: Docker-based deployment with compose files
- Environment Separation: Development, staging, and production configs
- Monitoring: Health checks, logging, and telemetry collection
- Scaling: Horizontal container scaling for execution workloads
- Identify the component: Determine if your work is frontend, backend, or SDK-focused
- Read component docs: Review the specific CLAUDE.md for detailed guidance
- Follow established patterns: Each component has established architectural patterns
- Test thoroughly: Use component-specific testing strategies
- Update documentation: Keep component-specific docs current
When changes affect multiple components:
- Plan the interface: Define clear contracts between components
- Update sequentially: Backend → Frontend → SDK (typical order)
- Maintain compatibility: Ensure backward compatibility where possible
- Test integration: Use testapps for end-to-end validation
- TypeScript First: Strict TypeScript across all components
- No
any
Types: Use proper typing throughout
- Consistent Formatting: Follow ESLint and Prettier configurations
- Clear Naming: Use descriptive names for functions, variables, and types
- Domain-Driven Design: Clear business domain separation (backend)
- Component Architecture: Focused, reusable components (frontend)
- API Compatibility: Maintain Genkit compatibility (SDK)
- Separation of Concerns: Each layer handles its responsibilities only
- Input Validation: Validate all inputs at component boundaries
- Authorization: Check permissions before actions, not just authentication
- Secure Communication: HTTPS only, secure session handling
- Code Execution: Isolated environments with resource limits
- Unit Tests: Component-specific business logic
- Integration Tests: Cross-component interactions
- End-to-End Tests: Complete user workflows via testapps
- Security Tests: Validate security boundaries and permissions
- Review component documentation: Read the relevant CLAUDE.md file
- Understand the architecture: Follow established patterns for your component
- Check existing implementations: Look for similar features to maintain consistency
- Follow component guidelines: Each component has specific development practices
- Write tests: Include appropriate tests for your component
- Handle errors gracefully: Implement proper error handling and user feedback
- Document changes: Update component documentation as needed
- Test thoroughly: Run component-specific tests and integration tests
- Check all components: Ensure changes don't break other components
- Update documentation: Keep CLAUDE.md files current with changes
- Follow commit conventions: Use clear, descriptive commit messages
<genkit_prompts hash="56fae31b">
Genkit Framework Instructions:
</genkit_prompts>