File and Directory Org.

​

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.