​
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.