PRD Guideline
Every feature PRD uses the same skeleton: twelve numbered sections in a fixed order. The order is not a matter of taste — each section answers one question, and the answers build up from the reasoning (why this feature exists) to the details (what it contains, how it looks, who may do what).
This page explains the principles that apply, then each section one by one, and closes with an empty skeleton that can be copied directly.
Principles
- Problem first, then solution. Start from who is struggling and why it is worth working on. The feature is the answer, not the starting point.
- Write what and why, not how. A PRD sets outcomes and constraints; how to build it is decided during implementation. Implementation details locked in too early go stale quickly.
- Write down what is not being done. Unwritten boundaries get filled with everyone’s own assumptions, and that only surfaces once things are already running.
- One sentence, one interpretation. Drop words that cannot be measured — fast, easy to use, as much as possible. Replace them with numbers, closed lists, or conditions that can be checked.
- If it cannot be tested, it is not finished being written. Every criterion must be able to pass or fail without debate.
- One thing, one name. The name used in the PRD is the same as the one used on screen, in code, and in discussions. Two names for one thing make people think there are two things.
- Unanswered questions are written as they are. An honest line left open is better than a guess that sounds certain.
- When a decision changes, the document is updated first. A PRD that is not maintained stops being a reference and becomes an archive.
Conventions
- Language. PRDs are written in Indonesian in
content/idas the source of truth and mirrored into English incontent/en, with identical file paths. In both languages, terms that are clearer in English — endpoint, entity, status, field, datatable — and section names stay in English. - The skeleton is fixed. Irrelevant sections are skipped, not filled with “Not applicable”, and there are no extra sections beyond those in the template.
- Unanswered questions are marked
**Needs confirmation**where they occur, not collected into a separate list. - A PRD only contains what has been decided. Ideas still under discussion belong in Non-goals, or do not need to be written yet at all.
Writing Order
The section order is designed to be easy to read, not easy to write. When filling it in, the following order usually flows best:
- Problem, then Goals & Non-goals — agree on the problem being solved and where the work stops.
- Business Rules — formulate the binding rules, since every later section rests on them.
- Flow and Status Lifecycle — make sure the process is complete, from start to end state.
- Document Structure, then UI Structure — turn rules into fields, then fields into screens.
- User Stories and User Scenarios — state the needs as testable criteria.
- Permissions & Actions, then Notifications and Dependencies — define who may do what, and what is affected.
- Overview last — summarize once the content is clear, because by then it is much easier to formulate.
Metadata Block
Every PRD opens with a title, three metadata bullets with bold values, then a horizontal rule:
# Purchase Order
- Code: **PUR-PO**
- Module: **Purchasing**
- Type: **Transaction**
---| Part | Rule |
|---|---|
| Title | # <Feature Name>, using the feature name agreed for that document’s language |
| Code | Three-letter module code, a hyphen, a feature abbreviation — PUR-PO, SET-EMP, ACC-NTF. Unique across the docs |
| Module | Name of its parent module |
| Type | The nature of the data managed by the feature, chosen from the closed list below |
There is no Status, Priority, Owner, or API in the metadata.
Type list. These four values determine the shape of the PRD, so decide on one before filling in the other sections:
| Type | For | Characteristics |
|---|---|---|
| Transaction | Documents that record a business event and are created repeatedly | Has a status, often has lines and calculations |
| Master Data | Reference data that is managed and then referenced by other features | Created, edited, deleted, and searched through a list |
| Configuration | Settings that change how the system behaves | Usually one record per scope, not created repeatedly |
| System Record | Data generated by the system, not entered by users | Read-only; at most deleted, revoked, or marked |
Section Summary
| # | Section | Answers | Required |
|---|---|---|---|
| 1 | Overview | What is this feature, and what is the expected outcome? | Yes |
| 2 | Problem | Why does this feature exist — what breaks without it? | Yes |
| 3 | Goals & Non-goals | What is pursued, and what is deliberately not done? | Yes |
| 4 | Business Rules | Which rules apply everywhere, whoever the actor is? | Yes |
| 5 | Flow | How does the process run, and which statuses does it go through? | Yes |
| 6 | Document Structure | Which fields does this data have, and what are their value rules? | Yes |
| 7 | UI Structure | How are those fields shown and operated on screen? | Yes |
| 8 | User Stories | Who needs what, and when is it considered done? | Yes |
| 9 | User Scenarios | What does real end-to-end usage look like? | Yes |
| 10 | Permissions & Actions | Who may do what, and in which status? | Yes |
| 11 | Notifications | Which events trigger notifications, to whom, and through which channels? | Yes |
| 12 | Dependencies | What does this feature depend on, and what does it affect? | Yes |
Numbering must not change. If a sub-section is not relevant, it is skipped — the main section number stays the same.
1. Overview
Purpose. Give the reader a complete understanding in a single read, without having to go into other sections.
Content. Two paragraphs. The first paragraph defines the feature: what the document is, its position in the larger business flow, and what sets it apart from neighboring features. The second paragraph always opens with Expected outcome: … and states the condition reached when the feature works.
Rules. Write from a business perspective, not an implementation one. No database table names, component names, or endpoints here.
2. Problem
Purpose. Record why this feature is being built, so its design decisions can be reconsidered later.
Content. One paragraph describing how this work runs without the feature, closed with As a result:, then bullets listing the concrete consequences.
Rules. Each bullet is a problem people actually feel, not a technical gap. Write “incoming goods are hard to match against the original agreement”, not “there is no relation between the receipt and order tables”.
3. Goals & Non-goals
Purpose. Lock the scope of work, so it does not quietly expand.
Content. Two sub-sections: ### 3.1 Goals and ### 3.2 Non-goals, each as bullets.
Rules.
- Goals are written as outcomes pursued, not a feature list. “Quantity or price differences are caught when goods are received” — not “there is a receive goods button”.
- Each Goal should answer one bullet in Problem.
- Non-goals contain things that would reasonably be expected but are deliberately not done, along with their replacement if any: “Sending POs to suppliers directly from the system; POs are downloaded as PDF and sent through each store’s own channels.”
4. Business Rules
Purpose. Be the single source of truth for this feature. If another part of the PRD appears to contradict it, the rules in this section prevail.
Content. A standard opening paragraph, then numbered bullets **BR-01**, **BR-02**, and so on.
Rules.
- One BR contains one complete rule, written as a statement that can be true or false — not a feature description.
- Rules apply throughout the application, on every screen and action, whoever performs it. A rule that only applies on one screen is not a BR; it is UI behavior and belongs in UI Structure or an AC.
- BR numbers are never reused. If a rule is removed, its number is retired, not filled with a new rule.
- Business Rules are the FE–BE contract: the backend enforces them, the frontend uses them as form validation.
5. Flow
Purpose. Show how the process runs from start to finish, and which statuses it goes through.
Content. Sub-sections ### 5.1 Main Flowchart and ### 5.2 Status Lifecycle. Each contains a Mermaid diagram followed by its explanation — with no extra heading between the diagram and the explanation.
5.1 Main Flowchart
A flowchart TD diagram, followed by a numbered list of steps explaining each node.
- The longest path is placed in the middle so the diagram is easy to read.
- Actions that return to the same status (editing data, assigning a PIC) are drawn as their own step with a two-way arrow
<-->, not a self-loop. - Written as a specification of system behavior, not a tutorial narrative. Write “the PO takes effect and its content is permanently locked”, not “staff click the Submit button and then press confirm”.
- Steps whose details belong to another PRD only need to be mentioned and pointed to, for example goods receiving, which is explained in the Goods Receipt PRD.
5.2 Status Lifecycle
A stateDiagram-v2 diagram, followed by a status table.
| Status | Description | Next |
|---|---|---|
| Draft | Being prepared, not yet in effect for the supplier | Submitted, or deleted |
- The Status column contains the display name, then its technical value in backticks on a second line, separated by
<br />— so the Draft cell contains the name Draft on the first line anddrafton the second. - The Next column names the statuses that can be reached next, or
—for a final status. - Features without a status do not have this sub-section. If a feature has another self-contained flow, add it as a new sub-section with the same pattern.
6. Document Structure
Purpose. Define the data itself — which fields it has, their type, which are required, their initial values, and their value rules. The provisions here apply wherever the data is created or changed and are enforced on save, regardless of how the field is displayed.
Content. Starts with one opening paragraph, then one table per sub-section with fixed columns:
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| Estimated Received Date | Date | Yes | — | Must not be earlier than the Order Date (BR-07) |
Sub-section naming.
- Document-level fields always live in
6.1 General. - Documents with lines continue with
6.2 Line Items, then6.3 Calculationsif there are derived values. - Derived collections are added as their own sub-section and named in the singular:
Address,Payment, not Addresses or Payments. Calculationsuses different columns —Field | Formula— because it contains derived values, not inputs.
Type dictionary. Used as is, with no new terms added:
| Type | For |
|---|---|
| Text | Free text, codes, document numbers |
| Integer | Whole numbers |
| Decimal | Fractional numbers, for example quantities |
| Currency | Monetary values |
| Percent | Percentage values |
| Enum | A choice from a fixed list; its values are named in the Rules column |
| Boolean | Yes/no, active/inactive |
| Date | Date only |
| Date & Time | Date along with time |
| File | Attachments or images |
| Object | Structured data that does not need to be split into fields |
Ref. <Entity> | A reference to other data: Ref. Supplier, Ref. Employee, Ref. Store Product Inventory |
The suffix , multiple means the field holds more than one value: Ref. Employee, multiple, File, multiple.
Column rules.
- Required contains
Yes,No,—for system-set fields, or the condition if conditional:Yes, if type is Custom. - Default contains the initial value or its origin:
Today,Generated on save,Follows the selected package. - Rules cites the underlying BR number in parentheses, and only contains value provisions — not screen behavior.
7. UI Structure
Purpose. Bridge “which fields” with “how those fields look and behave”. This section only governs display and interaction; content and value rules still follow Document Structure.
Content. An opening paragraph, then sub-sections matching the surfaces the feature has. Only write what is used — do not copy sub-sections that are not relevant.
Datatable
The list table’s columns, ordered left to right as on screen.
| Column | Sortable | Sample Value | Component |
|---|---|---|---|
| PO Number | Yes | PO/CBI/2026/000042 | Link |
Every datatable starts with the Select column (built-in checkbox and expand toggle) and No, then the feature’s columns, and ends with the Actions column. If rows can be expanded, their content is written as an Expanded Row table right below it.
Advance Filter
Advanced filters and the source of their options.
| Field | Control | Options Source | Default |
|---|---|---|---|
| Supplier | Multi Select | Supplier master, searchable | Empty |
Form & Details
Starts with three paragraphs marked in bold — Create, Edit, Detail — explaining the layout and actions of each mode. Modes that do not exist are skipped. Then one #### heading per form section, for example #### General, #### Products — Table, #### Products — Form, #### Products — Calculations.
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Supplier | Single Select | Supplier master, searchable | Changed → Contact is cleared |
The Behavior column uses the pattern <trigger> → <effect> and only contains screen behavior, for example fields that are cleared or recalculated when another field changes.
PDF Format
The layout of the printed document, section by section from top to bottom.
| Section | Content |
|---|---|
| Header | - Company: Name, Contact, Address<br />- Document: Title, Number, Date |
The Content column may contain bullets and bold emphasis to group its content. Columns describing a table layout are written separated by escaped pipes: No \| Product \| Quantity.
Other Surfaces
Features that are not list-and-form use names that match what they actually are, with the columns that explain them best: Feed for chronological lists, Grid & Map, Sync Dialog, Bell, Detail Dialog.
Component Dictionary
Used in the Component column, for things that are only displayed:
| Component | For |
|---|---|
| Text | Plain text |
| Number | Numbers |
| Date | Dates |
| Currency | Formatted monetary values |
| Badge | A status or colored label |
| Link | Text that opens another page |
| Thumbnail | A small image |
| Avatar | A person’s photo |
| Accordion | Collapsible content, for values with more than one item |
| Action Menu | A set of row actions |
| Checkbox | A selection marker |
| Expand Toggle | Opens the detail row |
| Add Button | An add button inside a cell |
Control Dictionary
Used in the Control column, for things that can be filled in or selected:
| Control | For |
|---|---|
| Text Input | Single-line text input |
| Textarea | Multi-line text input |
| Single Select | Choosing one from a list |
| Multi Select | Choosing more than one |
| Date Picker | Choosing one date |
| Date Range Picker | Choosing a date range |
| Date Time Picker | Choosing a date along with time |
| Number Input | Numeric input |
| Currency Input | Monetary input |
| Percent Input | Percentage input |
| File Uploader | Uploading files |
| Toggle | Turning on or off |
| Read-only | Displayed, cannot be changed |
The vocabulary in these two dictionaries is reused, not extended per feature. Calling the same thing by two different names (dropdown vs Single Select) makes readers think they are different.
8. User Stories
Purpose. State the needs per role along with the criteria that make them done — the basis for testing and acceptance.
Content. One heading per story, a need statement, then a criteria table.
### US-04 - Submit a PO
As a PIC, I want to submit a PO, so that the PO takes effect and its content no longer changes.
| ID | Acceptance criteria |
|---|---|
| AC-04.1 | The Submit Order button appears on a Draft PO ... (BR-02). |Rules.
- The story title is the activity, not a screen name. No priority and no introductory paragraph.
- The need statement uses the pattern
As a <role>, I want <need>, so that <benefit>. - AC numbers follow the story number: story
US-04usesAC-04.1,AC-04.2, and so on. - One AC contains one thing that can be checked as true or false, and cites the BR number if it enforces a rule.
- Use the button label shown on screen (“Submit Order”), not the short action name used in Flow and Permissions.
- Special cases are written as regular AC rows, using the pattern
<situation> — <expected behavior>. - If the correct behavior has not been decided, mark it
**Needs confirmation**and state what needs to be agreed. This is the only bold text allowed inside an AC.
9. User Scenarios
Purpose. Show real end-to-end usage — something not visible from User Stories, since each story only captures one need.
Content. A Role | Scenario table, three to four rows.
| Role | Scenario |
|---|---|
| Purchasing Staff | Creates a weekly restock PO to one supplier, assigns a PIC, then submits it and prints the PDF to send via WhatsApp |
Rules.
- One row is a sequence of steps, not a single action. Rows that merely repeat a User Story are removed.
- Include at least one scenario that crosses into other features, for example a PO that continues into goods receiving and billing.
- Role uses real roles in the field (Purchasing Staff, Owner, Admin, Auditor), not technical role names in the system.
10. Permissions & Actions
Purpose. Answer who may do what, and under which conditions the action is available.
10.1 Permission by Action
| Action | Permission | Condition |
|---|---|---|
View PO List<br />(All Stores) | purchase:purchase-order:list:any | — |
| Add Product | purchase:purchase-order:update:store <br /> purchase:purchase-order:create:store | Store is active |
Rules.
- One action per row. Actions are not combined with slashes; the same permission may appear in several rows.
- Stacked permissions mean AND. Two permissions written one above the other with
<br />are both required. Do not use plus signs or parentheses. - Scopes go in separate rows. The
:any(all stores) and:store(assigned stores) versions are written as two different rows. - Two-line labels. Long action names are shortened with a qualifier on the second line:
View PO Listthen(All Stores). - Condition contains non-permission requirements: store is active, user is the PIC, data is not yet linked. Fill in
—if there is none, or explain if it inherits another permission (“Follows the view PO detail permission”).
10.2 Action by Status
A matrix of actions against statuses, using ✓ for available and — for not available.
| Action | Draft | Submitted | Cancelled |
|---|---|---|---|
Edit PO<br />(General Data) | ✓ | — | — |
The order and naming of actions follow 10.1. This sub-section is skipped for features without a status; if the distinguishing axis is not status, use a fitting name such as 10.2 Action by Device.
11. Notifications
Purpose. Record the events in this feature that trigger notifications, so it is clear what the notification engine sends, to whom, and where the user lands when opening it.
Content. One table with the columns Event | Recipient | Title | Body | Destination, one row per event:
Event— the action or condition that triggers it, with a reference to theBR-xxthat governs it.Recipient— who receives it.Title— the exact title text shown in the notification.Body— the exact body text shown. Parts that change per event are written as variables in curly braces, for example{device name}.Destination— the page opened when the notification is clicked, written as a full address inside the app, for example/account/linked-devices; empty if none.
Channels are not written: the system automatically sends to all channels (inbox, in-app, and device) per the user’s settings in the Notifications PRD. Channel exceptions are written in Business Rules.
This section is required in every PRD. A feature that triggers no notifications still includes it, with a single sentence: “This feature does not trigger any notifications.” The rule for when a notification is sent stays in Business Rules; this table only summarizes the outcome.
12. Dependencies
Purpose. Show how this feature relates to other parts of the system, so the impact of a change in one place can be traced.
Content. Up to three bold groups, each with bullets:
**Related PRDs**— other features whose flows intersect, with a short reason.**Master data**— reference data used by this feature.**Effects on other modules**— consequences this feature causes elsewhere, including those that deliberately do not happen (“A PO does not change stock; stock increases when a GR is submitted”).
Empty groups are skipped.
Implementation Markers
The PRD leads, so part of it may not exist in code yet. Points that are not implemented are marked at the end of the point, whether in Business Rules, a Flow step, an AC row, or a field or UI row:
<mark>🚧 Not yet: BE</mark>— backend not done.<mark>🚧 Not yet: FE</mark>— frontend not done.<mark>🚧 Not yet: FE + BE</mark>— neither is done.
A point counts as not implemented if either side is missing. The label is reduced when one side is done and removed when both are.
Template
Copy the content of the block below into content/en/<application>/<module>/<feature>.md (and its Indonesian counterpart in content/id), then fill in each section following the explanation above.
The <!-- ... --> lines are content reminders; remove them once the section is filled in.
# Feature Name
- Code: **MOD-FEA**
- Module: **Module Name**
- Type: **Transaction**
---
## 1. Overview
<!-- Paragraph 1: what this feature is and its position in the business flow. -->
Expected outcome: <!-- the condition reached when this feature works. -->
## 2. Problem
<!-- Paragraph: how this work runs without this feature. --> As a result:
- <!-- a concrete consequence people feel -->
- <!-- a concrete consequence people feel -->
## 3. Goals & Non-goals
### 3.1 Goals
- <!-- an outcome pursued, not a feature list -->
### 3.2 Non-goals
- <!-- what is deliberately not done, with its replacement if any -->
## 4. Business Rules
Business rules are the set of provisions and constraints that apply to <!-- Feature Name --> throughout the application, on every screen and action that involves it, whoever performs it. These rules are the single source of truth: if another part of this PRD appears to differ, the rules here prevail.
- **BR-01** <!-- one complete rule that can be true or false -->
- **BR-02**
## 5. Flow
### 5.1 Main Flowchart
```mermaid
flowchart TD
S([Start]) --> N1[1. First Step]
N1 --> N2{2. Validation}
N2 -->|Invalid| N1
N2 -->|Valid| N3(3. Initial Status)
N3 --> E([End])
```
1. **First Step** — <!-- what happens in the system, not what the user clicks -->
2. **Validation** — <!-- what is checked and what happens if it fails -->
3. **Initial Status** — <!-- the state of the data after saving and what may come next -->
### 5.2 Status Lifecycle
<!-- Skip this entire sub-section if the feature has no status. -->
```mermaid
stateDiagram-v2
[*] --> Draft
Draft --> Submitted: Submit
Submitted --> [*]
```
| Status | Description | Next |
|---|---|---|
| Draft<br />`draft` | | Submitted |
| Submitted<br />`submitted` | | — |
## 6. Document Structure
This section defines the content of the <!-- Feature Name --> document itself: which fields it has, their type, which are required, their initial values, and their value rules. The provisions here apply wherever the data is created or changed and are enforced on save, regardless of how the field is displayed.
### 6.1 General
<!-- Documents with lines continue with 6.2 Line Items, then 6.3 Calculations. -->
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| | | | | |
## 7. UI Structure
This section defines how <!-- Feature Name --> is displayed and operated: <!-- name the surfaces it has -->. This section only governs display and interaction; content and value rules still follow Document Structure.
### 7.1 Datatable
| Column | Sortable | Sample Value | Component |
|---|---|---|---|
| Select | — | — | Checkbox, Expand Toggle |
| No | — | 1 | Number |
| | | | |
| Actions | — | View · Edit · Delete | Action Menu |
### 7.2 Advance Filter
| Field | Control | Options Source | Default |
|---|---|---|---|
| | | | Empty |
### 7.3 Form & Details
**Create** — <!-- layout and actions -->
**Edit** — <!-- layout, availability conditions, and actions -->
**Detail** — <!-- layout and actions shown per status -->
#### General
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| | | | |
## 8. User Stories
### US-01 - Activity Title
As a <!-- role -->, I want <!-- need -->, so that <!-- benefit -->.
| ID | Acceptance criteria |
|---|---|
| AC-01.1 | |
| AC-01.2 | |
## 9. User Scenarios
| Role | Scenario |
|---|---|
| | |
## 10. Permissions & Actions
### 10.1 Permission by Action
| Action | Permission | Condition |
|---|---|---|
| | `module:feature:action:scope` | — |
### 10.2 Action by Status
<!-- Skip if the feature has no status. -->
| Action | Draft | Submitted |
|---|---|---|
| | ✓ | — |
## 11. Notifications
<!-- If the feature triggers no notifications, replace the table with one sentence: This feature does not trigger any notifications. -->
| Event | Recipient | Title | Body | Destination |
|---|---|---|---|---|
| | | | | |
## 12. Dependencies
**Related PRDs**
- <!-- other features whose flows intersect, with the reason -->
**Master data**
- <!-- reference data used by this feature -->
**Effects on other modules**
- <!-- consequences this feature causes elsewhere -->
Reference. If this guide feels ambiguous, see Purchase Order — the PRD that fills in this skeleton most completely, from Business Rules to PDF Format, and serves as the reference when this document and its content appear to differ.