Projects
Default recommendation: Start with one project per product. Create separate projects only when teams have no release dependencies.
Decision framework
Use this framework to determine whether to create a separate project:
Use an existing project when
Code executes in the same process, application, or web page:
- Frontend and backend for a single-page application
- Multiple services in a monolith
- Components within the same web application
Applications are tightly coupled:
- Frontend depends on specific backend API versions
- Services communicate via internal APIs with hard dependencies
- Components must be released in lockstep
Create a separate project when
Applications are loosely coupled:
- Services communicate via public APIs with version management
- Services can be released independently
- Applications serve different products or business units
No coordination is needed:
- Applications have no release dependencies
- Teams work independently with no shared releases
- Applications serve different customer segments
Key benefits of shared projects
Sharing projects for tightly coupled applications provides:
- Prerequisites for coordinated releases across frontend and backend
- Approvals for collaborative change management
- Single pane of glass for release visibility
Important: Each flag needs a clear owner, even in shared projects. Avoid shared responsibility for individual flags.
What projects contain
Projects scope these resources:
- Feature flags: Shared across all environments in the project
- Flag templates: Standardized flag configurations
- Release pipelines: Automated release workflows
- Context kinds: Custom context type definitions
- Permissions: Project-scoped roles control access
Coordinating releases across projects
When applications in separate projects need to coordinate releases, use these strategies:
- Request metadata: Pass API version or client metadata in requests for server-side coordination
- Delegated authority: Grant teams permission to manage flags in other projects
To learn more about coordination strategies, read Coordinating releases.
Corner cases
Global flags
Scenario: Many loosely coupled microservices in separate projects need to change behavior based on shared state.
Solution: Pass shared state as custom context attributes. Identify a single source of truth and propagate evaluation results from the owner of the state, rather than duplicating the state across projects.
Onboarding new teams
Scenario: A new team joins and needs to integrate with existing applications.
Process:
- Determine if the new team has dependencies on flags in existing projects
- If dependencies exist, include the team in the shared project
- If no dependencies exist, create a separate project
- Document the coordination strategy if projects are separate
Organizing flags within projects
Use views to organize flags by tags and metadata within projects. This provides flexible grouping without creating additional projects.
To learn more, read Views.