Developer Resourcesdocumentation formats

Features and Flows Documentation Format

Detailed Fumadocs MDX format for module features, user flows, business rules, and lifecycle diagrams.

Features and Flows Documentation Format

Use this format for every module and submodule feature page. This doc explains what the module does for users, admins, workers, and systems, and how each flow behaves from start to finish.

Required Source References

Source	Required Use
Existing Fumadocs module docs	Use feature docs such as `banners/feature.mdx`, `search/feature.mdx`, and order module feature docs if present.
API doc	Required for route names, actors, auth, and response-visible behavior.
Backend doc	Required for service behavior, persistence, cache, jobs, and state transitions.
Current code	Required for exact route, status, permission, and side-effect behavior.

Frontmatter

---
title: MODULE_NAME Features and Flows
description: Complete feature list, actor journeys, state flows, business rules, edge cases, and diagrams for MODULE_NAME.
---

1. Documentation Evidence

Source Type	Files or Docs	What Was Extracted
Technical design	Sibling TDD doc	State, lifecycle, validation, timing.
API	Sibling API doc and controllers	Route surface and actors.
Backend	Sibling backend doc and services	Business behavior and side effects.

2. Feature Summary

Field	Value
Module	`MODULE_NAME`
Submodule	`SUBMODULE_NAME` or `N/A`
Primary user value	Explain in one sentence.
Actors	Guest, user, admin, worker, internal system.
Main entry points	Routes, jobs, scheduler, admin panel, mobile screen.
Main outputs	Responses, results, persisted records, events, notifications.
Related docs	API, backend, TDD.

3. Actor Matrix

Actor	Can Do	Cannot Do	Auth Requirement	Notes
Guest	Allowed actions.	Restricted actions.	None or guest identity.	Include guest persistence limits.
Logged-in user	Allowed actions.	Restricted actions.	JWT.	Include account stats/ownership.
Admin	Allowed actions.	Restricted actions.	Admin JWT + permission.	Include mutation and audit behavior.
Worker/system	Async actions.	N/A	Queue/internal.	Include retry/idempotency.

4. Capability Matrix

List every feature, including minor actions.

Capability	Surface	Actor	Route/Trigger	State Read	State Written	Linked API Section
Create entity	Admin	Admin	`POST /api/admin/...`	Existing records	New record	API section link.
Start session	Public/mobile	Guest/user	`POST /api/.../start`	Existing context	Session	API section link.
Enqueue job	Worker	System	Job trigger	Payload	Job result	API/backend section.

5. User-Facing Flows

Repeat for every user-facing flow.

5.x FLOW_NAME

Summary

Explain the flow from the actor's perspective.

Preconditions

Required auth state.
Required existing data.
Required catalog/pricing/session/cache state.
Required feature flags or config.

Main Flow

Step	Actor/System	Action	Result	Source
1	Actor	Performs action.	Request created.	API/controller.
2	Backend	Validates.	Accepted/rejected.	Service.
3	Backend	Persists/returns.	State changes.	Backend doc.

Branches and Edge Cases

Branch	Condition	Behavior	Error/Result
Validation failure	Invalid field.	Reject request.	`400`.
Missing data	Entity not found.	Stop flow.	Module error.
Guest branch	Actor not logged in.	Allow limited result.	No persistent record for guest actors.
Duplicate action	Same idempotency key/job id.	No duplicate side effect.	Existing result or no-op.

6. Admin Flows

Repeat for every admin flow:

Create.
List.
Read detail.
Update.
Reorder.
Activate/deactivate.
Soft delete.
Restore.
Export/import.
Moderation.
Manual retry.

6.x ADMIN_FLOW_NAME

Include route, permission, mutation side effects, cache invalidation, audit/logging, and failure branches.

7. Lifecycle and State Transitions

Document every state machine.

Entity	From	Event/Action	To	Guard Condition	Side Effects
`Entity`	`draft`	Activate	`active`	Required fields present	Cache invalidation.

Diagram:

9. Data and Side Effects by Flow

Flow	DB Writes	Cache Effects	Jobs	Realtime	Analytics	Notifications
Flow name	Tables	Keys invalidated	Queue jobs	Event names	Events	Email/push

10. Error and Recovery Flows

Scenario	Trigger	User/System Experience	Recovery	Source
Rate limited	Too many requests	`429` response	Retry later	Controller/guard.
Queue failure	Redis/BullMQ error	Request returns or fails depending code	Retry/DLQ/manual	Processor/service.
Cache failure	Redis unavailable	DB fallback or warning	Automatic	Service.

11. Diagrams Required Per Module

Every complete feature/flows doc should include:

Actor capability diagram.
High-level module flow diagram.
Sequence diagram for each major user/admin/system flow.
State machine diagram for every lifecycle.
Data side-effect diagram for write flows.
Error branch diagram for critical flows.

12. Mandatory Feature and Flow Deep-Dive Pack

This section is required for every generated feature/flows doc. The page must cover what the module does, why it does it, how users experience it, how admins operate it, how systems automate it, and what tradeoffs define the behavior.

12.1 Feature Inventory With Minor Behaviors

Every capability must be split into visible and hidden behavior.

Feature	Minor Behavior	Actor	Trigger	User/System Result	Backend Side Effect	Source
Feature name	Small behavior	Guest/user/admin/system	Route/job/action	What changes for actor	DB/cache/job/event	Source path/doc

Rules:

Do not group away minor behaviors such as restore, retry, skip, shuffle, filter, sort, empty result, fallback, cache miss, duplicate action, or permission failure.
If a user can notice it, an admin can configure it, a job can perform it, or a test asserts it, it must be documented.

12.2 Business Process Diagram Pack

Use diagrams that match the business flow.

Diagram	Required When	Purpose
User journey map	Always	Shows actor intent from entry to outcome.
Service blueprint	Multi-actor or backend-heavy flows	Separates user action, API, service, DB, jobs.
Activity diagram	Every major flow	Shows decisions and branches.
State diagram	Any lifecycle	Shows allowed transitions.
Swimlane diagram	Multi-actor flow	Shows ownership by actor/system.
Sequence diagram	API-backed flow	Shows call order.
Data side-effect graph	Any mutation	Shows DB/cache/job/event impacts.
Exception flow diagram	Critical failure scenarios	Shows recovery or terminal result.

Example swimlane-style flow:

Example service blueprint:

12.3 Business Rules and Policy Traceability

Every business rule must have implementation traceability.

Rule	Business Reason	Actor Impact	Enforced In	API Impact	Backend Impact	Tests
Rule text	Why it exists.	What actor sees.	DTO/service/schema	Route/response	Data/side effects	Spec path

Include:

Eligibility rules.
Visibility rules.
Ownership rules.
Ranking/scoring rules.
Moderation/safety rules.
Catalog and pricing rules.
Admin workflow rules.
Guest limitations.
Lifecycle rules.

12.4 Tradeoffs and Product Rationale

Document why the feature behaves this way.

Product Decision	User Benefit	Engineering Benefit	Alternative	Tradeoff	Risk
Decision	Benefit.	Benefit.	Alternative.	Cost.	Risk.

Examples:

Guest access allowed but persistence restricted.
Public endpoint rate-limited instead of login-only.
Async analytics instead of synchronous writes.
Page pagination instead of cursor pagination.
Fallback content instead of hard failure.
Server-authoritative pricing instead of client-supplied values.

12.5 Flow Edge-Case Matrix

Every flow needs edge cases.

Flow	Edge Case	Trigger	Expected Behavior	User/System Feedback	Source
Flow name	Duplicate action	Same request twice	Idempotent/no-op/error	Exact response/result	Code/test

Cover:

Empty state.
First use.
Last item.
Duplicate action.
Concurrent action.
Expired state.
Permission mismatch.
Guest limitation.
Missing dependency.
Cache stale/miss.
Queue failure.
Unsupported filter or sort option.

12.6 Flow-to-Data Trace

For each flow, show how feature behavior maps to data.

Flow	Reads	Writes	Cache	Jobs/Events	Response Fields
Flow name	Tables/cache	Tables/cache	Keys	Jobs/events	Visible fields

12.7 Experience Quality Checklist

The doc explains what the actor is trying to accomplish.
The doc explains what the backend does that the actor does not see.
The doc covers every minor flow and branch.
The doc includes user, admin, worker, and system flows where applicable.
The doc explains business logic, tradeoffs, and rationale.
The doc maps every flow to API routes and backend side effects.
The doc includes diagrams appropriate to each flow type.
The doc covers all edge cases and failure recovery.

13. Completion Checklist

Every feature, minor action, and submodule capability is listed.
Every actor has allowed and forbidden behavior.
Every major and minor flow includes steps, branches, and diagrams.
Every lifecycle has a transition table and state diagram.
Every flow links to the API and backend docs.
TDD dependencies are called out where they shape behavior.

Features and Flows Documentation Format

Features and Flows Documentation Format

Required Source References

Frontmatter

1. Documentation Evidence

2. Feature Summary

3. Actor Matrix

4. Capability Matrix

5. User-Facing Flows

5.x FLOW_NAME

Summary

Preconditions

Main Flow

Sequence Diagram

Branches and Edge Cases

6. Admin Flows

6.x ADMIN_FLOW_NAME

7. Lifecycle and State Transitions

9. Data and Side Effects by Flow

10. Error and Recovery Flows

11. Diagrams Required Per Module

12. Mandatory Feature and Flow Deep-Dive Pack

12.1 Feature Inventory With Minor Behaviors

12.2 Business Process Diagram Pack

12.3 Business Rules and Policy Traceability

12.4 Tradeoffs and Product Rationale

12.5 Flow Edge-Case Matrix

12.6 Flow-to-Data Trace

12.7 Experience Quality Checklist

13. Completion Checklist

See Also

On this page