​
Project Structure Overview

The Formbricks codebase follows a monorepo structure using pnpm workspaces, with two main directories:
  • apps/ - Contains full applications
  • packages/ - Contains shared libraries and utilities

​
Apps Directory

The apps/ directory contains complete applications:

​
apps/web/

  • Main Formbricks web application (Next.js)
  • Primary application with full feature set
  • Uses App Router architecture
  • Contains environment-specific settings and configurations

​
apps/demo/

  • Demo application (Next.js)
  • Showcases Formbricks in-product surveying functionality
  • Used for testing and demonstration purposes

​
apps/demo-react-native/

  • React Native demo app (React Native)
  • Demonstrates mobile integration capabilities
  • Example implementation for React Native

​
apps/storybook/

  • Component documentation
  • Visual documentation of UI components
  • Testing environment for isolated components

​
Packages Directory

The packages/ directory contains shared libraries and utilities:

​
packages/js-core/

  • Contains core functionality for in-product surveys
  • Shared logic between different SDK implementations
  • Base classes and utilities

​
packages/js/

  • JavaScript SDK for browser-based applications
  • Used for running surveys on websites and web apps (browser)
  • Public NPM package

​
packages/react-native/

  • React Native SDK
  • Used to run surveys in mobile apps built with React Native / Expo
  • Includes native platform adaptations

​
packages/lib/

  • Shared business logic
  • Shared utilities and helpers

​
packages/types/

  • TypeScript type definitions
  • Zod schemas for validation

​
packages/database/

  • Database schemas and migrations
  • Prisma schema definitions
  • Migration management

​
packages/surveys/

  • Survey-specific functionality
  • Survey rendering logic and UI components
  • Survey state management

​
Module Organization

​
Core Module Structure

Each feature module follows a consistent structure: 
modules/
└── ee/
├── insights/
│ ├── components/
│ ├── experience/
│ └── types/
└── contacts/
├── segments/
└── components/

​
Adding New Code

​
New Features

When adding new features, follow these guidelines:
  1. Determine Scope:
    • Complete application → apps/
    • Shared library → packages/
    • Feature for existing app → appropriate module in apps/web/modules/
  2. Module Creation: Create a new module with the standard structure: 
    modules/
└── your-feature/
    ├── components/    # React components
    ├── lib/           # Business logic
    ├── types/         # TypeScript types
    ├── actions.ts     # Server actions
    └── route.ts       # API routes
  3. Component Organization:
    • Base UI components → modules/ui/components/
    • Feature-specific components → modules/[feature]/components/

​
Best Practices

​
Code Organization

  • Keep modules focused and single-purpose
  • Maintain clear separation between UI and business logic
  • Use proper TypeScript interfaces and types

​
File Structure

  • Group related files in descriptive directories
  • Use consistent naming patterns
  • Keep files focused and modular

​
Module Independence

  • Minimize dependencies between modules
  • Share common utilities through appropriate packages
  • Maintain clear module boundaries

​
Documentation

  • Document complex logic and APIs as laid out in the Documentation section
  • Keep documentation current with code changes

​
Testing Organization

​
Test File Location

  • Test files should be located alongside the code they test
  • Use .test.ts or .spec.ts suffix for test files
  • Example: user-service.test.ts for user-service.ts

​
Test Directory Structure

feature/
├── tests/ # Test directory (if grouping tests)
├── components/ # Feature components
└── lib/ # Business logic

​
Configuration Files

​
Root Level Configuration

  • .eslintrc.js - ESLint configuration
  • tsconfig.json - TypeScript configuration
  • package.json - Package metadata and scripts
  • .env - Environment variables

​
Package Level Configuration

Each package maintains its own configuration files:
  • package.json - Package-specific dependencies and scripts
  • tsconfig.json - Package-specific TypeScript settings
  • .eslintrc.js - Package-specific linting rules

​
Version Control

​
Git Organization

  • .gitignore - Specifies ignored files and directories
  • .github/ - GitHub specific configurations and workflows
  • CHANGELOG.md - Documents version changes
  • LICENSE - License information

​
Conclusion

Following these organizational patterns ensures:
  • Consistent code structure across the project
  • Easy navigation and maintenance
  • Clear separation of concerns
  • Scalable architecture for future growth
Remember to maintain these patterns when adding new code to keep the codebase organized and maintainable.