Skip to content
Features GitHub

The concept

What is a feature-based architecture?

An approach that organizes code and folders around features, the business capabilities of your product, rather than around technical layers like components, services or utils.

Horizontal vs vertical

Slice your code like your product

A layered codebase cuts the product horizontally: one feature is spread across every technical folder. A feature-based codebase cuts it vertically: each feature is one column you can see, own and measure.

Layered organized by technical role

To understand auth, you read four folders.

Feature-based organized by business capability

To understand auth, you open one folder.

In practice

The same code, two structures

Highlighted files all belong to the “save user” feature. In a layered tree they are scattered; in a feature tree they live together, with a README that names the owner.

layered structure
src/
components/
UserForm.ts # save user
EmailInput.ts # save user
InvoiceTable.ts
hooks/
useSaveUser.ts # save user
useInvoices.ts
utils/
transformUser.ts # save user
formatPrice.ts
feature-based structure
src/
features/
saveUser/ owner: team-accounts
components/
UserForm.ts
EmailInput.ts
utils/
useSaveUser.ts
transformUser.ts
README.md
invoices/ owner: team-billing
components/ # shared across features

Why it works

Benefits of a feature-based architecture

  • Modular

    Each feature lives in its own self-contained folder with everything it needs.

  • Maintainable

    Changing a feature means working in one place, not across five technical folders.

  • Scalable

    Complex systems are broken down into smaller parts that teams can own independently.

  • Shared language

    Product managers, designers and stakeholders recognize the business features in the code.

  • Recursive

    Features can contain features. Structure grows with the product, at any depth.

  • Complementary

    It does not replace hexagonal or clean architecture. It organizes them around the business.

Anatomy of a feature

Everything about a feature, in its folder

Features reads each part of the folder to build its reports. Nothing to configure: the conventions are the configuration.

src/features/saveUser
saveUser/
README.md # description + owner
__docs__/
decisions/
001-use-jwt-tokens.md # MADR decision
components/
UserForm.ts
utils/
useSaveUser.ts # // TODO counted as debt
features/ # nested features
emailValidation
README.md
The first line after the title becomes the description. The owner front matter property sets the team.
__docs__/decisions/
Architecture decision records in the MADR format, listed with the feature.
source files
Lines of code, files, git history, coverage and TODOs are all computed per feature.
features/
A nested features folder holds sub-features, with ownership inherited from the parent.
Feature page in the Features dashboard: Feature 1 with its path, owner and metadata, its nested features in the sidebar, and tabs for changes, tests, decisions, insights, dependencies and flags
In the dashboard, nested features appear under their parent and every part of the folder gets its own tab.

Good to know

Feature-based architecture is not feature-based design

Close to DDD, more structured

It is similar to domain-driven design, but more recursive and more structured. It is also easier to understand for beginners, which makes it a good default for growing teams.

Further reading

Read the guidelines to structure your project →

Map your own features

No configuration, no account. Point the CLI at a folder and open the dashboard.

$ npx features-cli@latest serve ./src
Open the live demo Star on GitHub