Why Code Alone Isn't Enough: The Case for Spec-Driven Development

https://ainativedev.io/news/from-code-centric-to-spec-centric

Spec-Driven Development: An Initial Review

https://dev.to/danielsogl/spec-driven-development-sdd-a-initial-review-2llp

I am looking for nomenclature for feature sets, feature, screen flow, screen etc to plan out development of app. What is the correct way to describe all this. Give me a brief comprehensive answer.

Product architecture: a clean hierarchy for planning apps

Clear structure reduces guesswork. Whether you're sketching a new feature on a napkin or preparing a roadmap for your next release, a consistent hierarchy — from product-level thinking down to individual tasks — keeps teams aligned and shipping faster. Below is a compact, practical breakdown you can use as a blueprint when planning, designing, and implementing features for any modern app.

Product Module Feature User Story Task

1. Overview: Product → Module → Feature → Story → Task

Start broad, then get specific. Use this chain to decompose big ideas into implementable work:

Product — the entire application or service (the north star).
Module — a major area or capability (e.g., Authentication, Dashboard, Photos).
Feature — a concrete piece of functionality inside a module (e.g., Login with email, Photo annotations).
User Story — what the user does and why (e.g., "As a user, I can reset my password via email").
Task — developer-sized work items (API endpoints, UI screens, tests).

2. Screen hierarchy & UI building blocks

Map features to screens and components so design and engineering can move in parallel.

Screen (View) — a single UI the user sees (e.g., Job Details screen).
Screen Flow — how screens connect (Login → Onboarding → Dashboard).
Component — reusable UI elements (cards, inputs, grids).

3. Supporting terms & artifacts

Epic — a large body of work spanning multiple features or quarters.
Wireframe — low-fi visual layout for alignment and quick iteration.
Mockup / Prototype — higher-fidelity visuals used for testing and handoff.

4. Practical planning tips

Use Epics for big outcomes, then break them into Modules/Features for teams to own.
Write User Stories from the user's perspective — acceptance criteria first.
Keep Tasks small and testable: a developer should be able to estimate them accurately.
Map features to screens early to avoid UI surprises during implementation.
Make components reusable — design system thinking pays off.

5. Quick checklist to use right now

Define the Product goal (one-sentence).
List 3 Modules that directly support that goal.
For each Module, write 2–3 Features and one User Story per Feature.
Break the highest-priority Feature into Tasks ready for dev.

In terms development, how does the database or data model fit in to the process. Is it design and generated along side the UI UX? Is it done all at once? If I want to use a prd and feed it to cursor how do features and database fit into it. What's best practises

From PRD to Production: Designing Features and Databases Together

Shipping a great app means balancing product thinking (what the app should do) with solid data design (how the app stores and serves that information). Below is a practical roadmap for taking a Product Requirements Document (PRD) and turning it into a clean, maintainable data model and implementation plan — without overbuilding or blocking the product team.

1. Start with the PRD (Product Requirements Document)

The PRD defines what the product must do — features, user stories, and flows. It should remain implementation-agnostic: product and UX decide scope and success criteria; engineering translates those into technical requirements.

2. Translate Features into Entities & Relationships

Each feature implies data. Capture that early:

“Users can post comments” → User and Comment models with a foreign key.
“Photo uploads” → store file metadata, EXIF JSON, GPS, dimensions, and a storage path.
Define ownership & multitenancy up front (e.g., org_id on tenant-scoped tables).

3. Best Practices in Timing

Don’t attempt a full, final database design up front. Instead:

Create a baseline schema (auth, users, core entities).
Evolve schema incrementally, feature-by-feature, aligned with sprints.
Use migrations and feature flags so schema changes are reversible and safe.

4. Development Workflow (UI + DB in sync)

For each user story:

Design the UI flow and wireframe the screens.
List the data requirements: tables, fields, relationships, and access rules.
Create the API contracts and business logic sketches.
Author migrations and tests, then implement UI + API together so the app remains functional end-to-end.

5. Where the Database Fits

Think of the database as the backbone of features. Every user story maps to:

UI (screens and flows)
API/business logic
Database schema and access policies (RLS, roles)

The PRD should call out data needs for each feature, not just UX behavior.

Summary — Practical Rules of Thumb

PRD = what. Product defines outcomes and acceptance criteria.
Features → Data. Every feature should include a short “data requirements” section.
Evolve incrementally. Build a minimal schema and grow it with migrations and tests.
Ship UI + DB together. Implement UI, API, and schema changes in the same feature to keep things consistent.
Use tools. Generate types from your DB, use SQL-first ORMs, and enable RLS for security.

Want a ready-to-use PRD template that includes a per-feature "data requirements" section and sample DB migration snippets you can drop into your repo? I can draft one tailored to your stack (Postgres + Supabase, Prisma, or Drizzle).

PRD

Product Requirements Document — Practical Template

Shipping a product needs clarity: what you're building, who it's for, and how the pieces connect. Below is a compact, developer-friendly PRD template that ties features to user flows and the underlying data model — ready to paste into a blog post or a team wiki. It’s designed to look crisp on dark backgrounds and to be immediately actionable by PMs, designers, and engineers.

1. Overview

Product Name: [your product name]
Summary: High-level description — what the app does and for whom.
Goals: Top 3 measurable goals and business value.
Non-Goals: What we’re explicitly not solving in this release.

2. Epics / Modules

List the major functional areas — each becomes an epic with a short description.

Epic Name: Authentication — Signup, login, SSO
Epic Name: Dashboard — Overview, metrics, quick actions
Epic Name: Photo Management — Upload, tag, annotate, reports

3. Features

For each epic, list features with priority and dependencies.

Feature: Direct Photo Upload Priority: High

Description: Upload photos from web or mobile, with EXIF extraction and thumbnail generation.

Dependencies: Signed upload URLs, storage webhook, thumbnail pipeline.

Feature: Inline Photo Annotations Priority: Medium

Description: Annotate photos and save structured notes tied to jobs/properties.

Dependencies: Photo model, notes table, realtime events.

4. User Stories & Flows

Define stories in a standard format and attach acceptance criteria.

Example: As a field contractor, I want to upload photos from my phone so that I can attach them to a job estimate.

Flow: Camera → Signed upload URL → Storage webhook → EXIF extraction → Photo row created → Thumbnail ready.

Acceptance Criteria:

Upload retries on poor connectivity.
EXIF data is extracted and stored.
Photo appears in the job album within 10s of upload completion.

5. UI / UX Notes

Screens: Login, Dashboard, Job page, Album view, Photo detail.
Design patterns: Virtualized photo grid, optimistic UI for uploads, PWA offline queue.
Accessibility: Keyboard navigation, high-contrast labels, screen-reader summaries for photos.

6. Data Model Requirements

Define entities, attributes, and relationships. Example schema (simplified):

Entities:
  User
    - id (PK)
    - email (string)
    - password_hash (string)
    - created_at (timestamp)

  Organization
    - id (PK)
    - name (string)
    - billing_info (jsonb)

  Photo
    - id (PK)
    - org_id (FK → Organization.id)
    - storage_path (string)
    - exif (jsonb)
    - gps (geography)
    - width, height (int)
    - hash (string)
    - status (enum: uploading, processing, ready)
    - created_at (timestamp)

Relationships:
  - One Organization has many Users (org_members).
  - One Photo belongs to an Organization and optionally to a Job/Property.

7. Technical Considerations

Backend: Postgres (RLS), Edge Functions for secure server-side jobs, storage with signed URLs.
Auth: Supabase/Auth helpers or SSO; role-based access via RLS policies.
Performance: CDN + thumbnail-first delivery, lifecycle policies for storage retention.
Integrations: Slack/webhooks, PDF report generator, cloud drives for exports.

8. Tasks / Tickets

Break each feature into engineering tasks and testing workstreams.

Backend: API endpoints, DB migrations, RLS policy definitions, Edge Function stubs.
Frontend: Upload component, optimistic UI, virtualized grid, annotation tools.
Testing: Unit tests, integration tests for upload pipeline, RLS policy tests, e2e for user flows.
DevOps: Staging environment, Vercel previews, monitoring for storage & bandwidth costs.

Quick implementation checklist

Define org-scoped schema & enable RLS on every table.
Create upload pipeline: signed URLs → webhook → EXIF + thumbnails → update DB.
Build optimistic upload UI with offline queue and retries.
Add monitoring for storage cost, bandwidth, and function runtime.
Ship an MVP with core flows and iterate based on metrics and feedback.

Should I create a separate prd for each feature set, feature or epic?

The Blueprint for Modern PRDs: One Source of Truth

Structuring your Product Requirements Document correctly is crucial for clarity and alignment. Instead of creating a fragmented mess of documents, follow this simple hierarchy to keep your team on the same page from vision to execution.

1. One PRD per Product (or Major Release)

A PRD is typically the single source of truth for the whole product or a major release version (e.g., v1.0 PRD).

Inside it, you break down into Epics → Features → User Stories → Tasks.

This keeps everything in context and avoids fragmentation.

2. Use Sub-Docs for Large Products

If the app is big, create:

Master PRD (high-level vision, epics, priorities).
Feature Specs (separate docs for complex epics/features, more detail).

These feature specs are sometimes called FSDs (Functional Spec Documents) or Feature Briefs. The PRD then links out to them.

3. Best Practice

Don’t split PRDs by feature set — keep one central PRD for traceability. If needed, make feature-specific specs as children docs.

That way:

Product team sees the big picture.
Developers/designers can dive into feature-level detail when implementing.

4. Feeding to Cursor (or any AI Assistant)

Feed the master PRD to give Cursor the context of the app. Then, for coding, give Cursor the feature-specific section (user stories + data model). This avoids overwhelming it while keeping things modular.

🔑 Rule of thumb:

PRD = one per product/release.
Feature specs = optional sub-docs when detail is heavy.

Do this. Do you want me to also make you a sample filled-out PRD (like a mini login system example) so you can see how to connect features + data model in practice?

Understanding the Login & Authentication Flow

Secure login and authentication are the backbone of any web application. Understanding the flow from user registration to password resets helps developers build reliable and user-friendly experiences while keeping sensitive data safe. Below is a detailed text-based diagram of a typical login system, along with its database and session interactions.

[ Welcome Screen ]
     ├── (New user) → [ Registration Screen ] 
     │        → POST /register → [ Auth API ] 
     │        → Insert into [ User Table ]
     │        → Create [ Session/JWT ]
     │        → Redirect → [ Dashboard ]
     │
     └── (Existing user) → [ Login Screen ]
              → POST /login → [ Auth API ]
              → Validate against [ User Table ]
              → Create [ Session/JWT ]
              → Redirect → [ Dashboard ]

[ Login Screen ]
     └── (Forgot password) → [ Forgot Password Screen ]
              → POST /forgot-password → [ Auth API ]
              → Insert token into [ PasswordResetToken Table ]
              → User clicks email link → [ Reset Password Screen ]
              → POST /reset-password → [ Auth API ]
              → Update password in [ User Table ]
              → Redirect → [ Login Screen ]

In this flow:

UI Screens: Welcome, Registration, Login, Forgot, Reset, Dashboard.
Backend/API: Register, Login, Forgot-password, Reset-password.
Database: User table + PasswordResetToken table.
Session Layer: JWT or session created after login or registration.

This text-based approach makes it easy to visualize the authentication process without needing a graphic tool, while clearly showing how users interact with the system at each step.

Designing a Secure Authentication System: ERD Overview

Building a reliable authentication system is crucial for any web application. A clear and well-structured database design ensures user data is safe, reset flows work smoothly, and developers can scale the system confidently. Below is an Entity-Relationship Diagram (ERD) that outlines the core components of a secure authentication system.

+-------------------+
|      User         |
+-------------------+
| id (PK, UUID)     |
| email (string)    | UNIQUE, INDEX
| password_hash     | string
| created_at        | datetime
| updated_at        | datetime
+-------------------+
           |
           | 1-to-many
           |
           v
+-----------------------------+
|   PasswordResetToken        |
+-----------------------------+
| id (PK, UUID)               |
| user_id (FK → User.id)      |
| token (string, UNIQUE)      |
| expires_at (datetime)       |
+-----------------------------+

Key Points

User: Core table holding account information.
PasswordResetToken: Temporary tokens linked to a user for password resets.
Relationship: One User can have many PasswordResetTokens; each token belongs to exactly one User.
Constraints: Emails and tokens must be unique. Tokens expire after a set time.

This ERD maps directly to typical authentication flows. When a user registers, a User record is created. When they request a password reset, a PasswordResetToken record is created. Having this structure in place ensures your authentication system is both secure and maintainable.

Web Developer Tips

Search This Blog

Professional Software Development Terms and Processes: Spec-Driven Development