Skip to content

v3.0.0 - Architectural Decision Framework

Choose a tag to compare

View all tags
@munair munair released this 04 Nov 08:04
· 28 commits to main since this release
v3.0.0
384e4f3

🎯 Major Architectural Framework Addition

BREAKING CHANGES: Complete architectural decision framework for frontend/backend responsibility separation.

This release represents a fundamental paradigm shift in how AI assistants generate PRDs, preventing common mistakes where business logic defaults to the frontend.

🚀 Key Features

Section 2: Architectural Boundaries Framework (113 lines)

Backend Responsibilities:

  • Business logic, data aggregations, heavy computations
  • Multi-symbol operations, data normalization
  • Security operations, caching, external API integration

Frontend Responsibilities:

  • UI state management, presentation logic
  • Progressive disclosure, client-side validation
  • Visual calculations, user preferences

5-Question Decision Framework:

  1. Does this require data from multiple sources?
  2. Is this a calculation or transformation?
  3. Will multiple clients need this?
  4. Does this affect performance?
  5. Is this security-sensitive or rate-limited?

Enhanced PRD Requirements

  • Mandatory [Backend/Frontend] prefix in functional requirements
  • Required "Architectural Decisions" section in both Quick Start and Full PRD
  • Format: FR1: Backend: Calculate P/C ratios during options chain processing

PRD Review Checkpoint: Architectural Audit

  • 5-point checklist before finalizing PRD
  • Red flags detection system
  • Self-auditing capability for AI assistants

💡 The Problem This Solves

Before v3.0.0, AI-generated PRDs frequently contained these anti-patterns:

  • ❌ "Frontend calculates P/C ratio from options data"
  • ❌ "Frontend fetches multiple symbols and compares Greeks"
  • ❌ "Frontend aggregates volume data across expirations"
  • ❌ "Frontend calculates moving averages from price history"

After v3.0.0, the framework forces explicit architectural decisions:

  • ✅ "Backend includes P/C ratio in response payload"
  • ✅ "Backend multi-symbol comparison endpoint returns normalized comparison data"
  • ✅ "Backend includes aggregated volume metrics in expiration summary"
  • ✅ "Backend includes SMA-20/50/200 in market data response"

🎁 Impact on AI-Generated PRDs

Teams adopting v3.0.0 gain:

  • Consistency: All PRDs follow "Smart Backend, Simple Frontend" principle
  • Future-Proofing: Backend APIs designed to support future clients (mobile, desktop, API consumers)
  • Performance: Heavy computations happen on backend, not repeated in every client
  • Maintainability: Business logic in one place, not duplicated across frontend components
  • Security: Security-sensitive operations explicitly assigned to backend
  • DRY Principle: Data transformations happen once on backend, not repeatedly on each client

📚 Framework Philosophy

"Smart Backend, Simple Frontend": Business logic and calculations belong on backend; frontend focuses on presentation and UX.

"Backend-First Thinking": For data features, start by designing the ideal API response, then build frontend to consume it.

"Single Source of Truth": Data transformations happen once on backend, not repeatedly on each client.

🔧 Breaking Changes

  1. PRD Format: Functional requirements now require [Backend/Frontend] prefix
  2. PRD Structure: "Architectural Decisions" section now mandatory in both Quick Start and Full PRD
  3. File Locations: Active PRDs move from /documentation/ to /documentation/specifications/active/
  4. Decision Process: Step 3 of Application Process now requires architectural verification
  5. Examples Format: All examples updated to show architectural separation

📖 Migration Guide

From v2.x to v3.0.0:

  1. Functional Requirements Format Change: Update all functional requirements to use architectural prefix

    • Old: FR1: The system must calculate P/C ratios
    • New: FR1: Backend: Calculate P/C ratios during options chain processing

  2. Add Architectural Decisions Section: All PRDs now require explicit architectural decisions section before functional requirements

  3. Apply Decision Framework: For each requirement, answer the 5 questions to determine placement

  4. Run Architectural Audit: Before finalizing PRD, verify checklist and check for red flags

  5. Update Examples: Review existing PRDs for frontend calculations, aggregations, or multi-step API calls and refactor to backend

✨ Real-World Validation

This framework was developed after observing systematic mistakes in AI-generated PRDs across multiple projects:

  • Options trading platforms putting Greeks calculations in React components
  • Multi-symbol comparison features making parallel frontend API calls
  • Volume aggregation happening in browser instead of Lambda functions
  • Moving average calculations duplicated across web and potential mobile clients

The architectural framework eliminates these patterns before implementation begins, saving days of refactoring.

🔗 Resources

Full Changelog: v2.0.0...v3.0.0

Assets 2
Loading