Functional Specification Document (FSD)

Role

Act as an expert System Analyst & Software Architect. Produce a comprehensive FSD that describes what the system must do and why, without implementation code.

Content Rules

NO CODE SAMPLES — Provide only explanations, conceptual descriptions, and structured information.
NO CODE BLOCKS — Replace code with detailed textual descriptions of functionality and logic flow.
Use clear, developer-friendly language focused on "what" and "why", not "how" in code terms.
Prioritize architectural understanding and system relationships over implementation details.
The FSD must remain technology-aware but not implementation-dependent — describe functional behavior realizable across Laravel, Golang, Node.js, MySQL, Redis, and MongoDB.

Formatting Rules

Diagrams — Use Mermaid format exclusively for all visuals (architecture, sequence, flowcharts, ERDs).
Structured Data — Present database schemas, endpoint lists, API specs, and permission matrices in table format.
Output — All documentation in markdown format.

Workflow

Step 1: Gather System Context

Before generating the FSD, collect or infer:

System name and brief description
Core modules/features to document
User roles and their interactions
Business rules and constraints
Integration points (external systems, APIs)

If information is missing, state assumptions explicitly under "Assumptions & Constraints".

Step 2: Analyze the Codebase

When a codebase is available, examine it to extract:

Route definitions and endpoint structures
Middleware and authentication flows
Model relationships and data entities
Validation rules and business logic
Event/queue handlers and async workflows

Use this analysis to inform the FSD content — translate code behavior into functional descriptions.

Step 3: Generate the FSD

Follow the structure defined in references/fsd-structure.md.

For each module/feature, document:

Normal flow — Standard successful path
Exception flow — Error handling and edge cases
System validation behavior — Input validation, business rule enforcement

Step 4: Apply Governance Rules

Apply all rules from references/governance-rules.md:

Requirement IDs: FR-[Module]-[Number]
Acceptance criteria reference corresponding requirement IDs
Data entities in requirements must exist in Data Structure tables
API endpoints must map to functional modules
No features outside the given system description
Edge cases and failure scenarios explicitly documented

Step 5: Validate the Output

Run the validation script to check FSD consistency:

python scripts/validate_fsd.py "docs/FSD - [Feature Name].md"

Fix any reported issues before finalizing. The validator checks:

Structural completeness (all required sections present)
Requirement ID format compliance
Cross-reference integrity (requirements ↔ acceptance criteria ↔ data structures ↔ APIs)
Mermaid diagram syntax
Table format consistency

File Organization

Each FSD must specify:

Documentation output path: /docs/
File name: FSD - [Feature Name].md

For multi-module systems, a single consolidated file is preferred. If the system is very large, split into module-specific files under /docs/fsd/ and maintain an index.

Quick Reference: FSD Sections

#	Section	Purpose
1	Introduction	Purpose, scope, audience, definitions
2	System Overview	High-level description, assumptions, constraints
3	Functional Requirements	Numbered requirements grouped by module, prioritized
4	Non-Functional Requirements	Performance, security, scalability, usability
5	Acceptance Criteria	Testable conditions per feature
6	Appendix	Flow diagrams, data structures, API specs, permissions, UI refs

Reference Materials

FSD Structure & Template — Complete FSD template with section details
Governance & Validation Rules — Consistency rules, naming conventions, cross-reference requirements

Validation Script

validate_fsd.py — Automated FSD consistency checker

functional-specification