# Micro-SaaS PRD & Technical Specification Blueprint ==================================================================== MODULE 1: EXECUTIVE PRD & GHERKIN USER STORIES ==================================================================== - Product Vision, Value Proposition & Target User Personas: * Product Name: FeedbackPulse * Vision: A lightweight, embeddable customer feedback widget and public roadmap platform that uses AI to automatically cluster feature requests into actionable engineering priorities. * Target Personas: Bootstrapped SaaS founders, Solo Indie Hackers, and Product Managers at Seed-stage startups who are overwhelmed by messy customer feature requests across Discord, Slack, and email. * Monetization: Starter Tier ($29/month: 1 workspace, up to 500 active feedback posts) | Pro Tier ($79/month: Unlimited posts, AI automatic sentiment clustering, custom CNAME domain). - Core Feature Scope Matrix: | Feature Name | User Value | Complexity | Priority | | :--- | :--- | :--- | :--- | | Embeddable Feedback Widget | Captures user requests directly inside client web apps without context switching. | Medium | MVP | | Public Voting Roadmap | Transparent Upvoting board (Under Review, Planned, In Progress, Live). | Low | MVP | | AI Topic Clustering | Automatically groups similar semantic requests into a single root feature ticket. | High | MVP | | Custom CNAME Domain | Allows Pro customers to host feedback on `roadmap.theirbrand.com`. | Medium | Phase 2 | | Discord/Slack Webhook Sync | Broadcasts new trending features to internal team communication channels. | Low | Phase 2 | - 3 Detailed User Stories with Gherkin Acceptance Criteria: * Story 1: Workspace Creation & Team Provisioning As a new SaaS founder, I want to create a branded workspace and generate an embed code, so that I can immediately start collecting feedback from my active users. - Scenario: Successful Workspace Provisioning Given a newly authenticated user with no active workspaces, When they submit the workspace onboarding form with a valid name ("DevTool") and subdomain slug ("devtool"), Then a new workspace record is inserted, the user is assigned the OWNER role, and the system outputs a personalized JavaScript embed snippet with their unique `workspace_id`. * Story 2: Feedback Submission & AI Semantic Deduplication As an end-user of a SaaS product, I want to submit a feature idea and see if someone else already asked for it, so that I don't create duplicate requests. - Scenario: Submitting an existing idea triggers upvote suggestion Given a user typing "Add dark mode support" into the feedback input field, When the input length exceeds 10 characters, Then the system executes an embedding similarity search and renders a "Similar Requests" dropdown showing "Dark theme toggle", allowing the user to 1-click upvote the existing post instead of creating a duplicate. * Story 3: Stripe Billing & Quota Gating As an authenticated workspace owner, I want to upgrade to the Pro plan, so that I can unlock AI sentiment clustering. - Scenario: Usage limit threshold reached on Starter plan Given a workspace on the Starter plan with 500 feedback items, When an end-user attempts to submit the 501st feedback item, Then the submission is accepted, but the workspace owner receives an automated email and sees an in-app banner stating: "Starter limit reached. Upgrade to Pro to view new submissions." ==================================================================== MODULE 2: DATABASE ARCHITECTURE & SUPABASE / POSTGRESQL DDL ==================================================================== - Entity Relationship Overview: * `workspaces` (1) ---> (N) `workspace_members` * `workspaces` (1) ---> (N) `feedback_posts` * `feedback_posts` (1) ---> (N) `votes` * `feedback_posts` (1) ---> (N) `comments` - Production PostgreSQL / Supabase SQL Schema (DDL): ```sql -- Enable UUID extension CREATE EXTENSION IF NOT EXISTS "uuid-ossp"; -- 1. WORKSPACES TABLE CREATE TABLE workspaces ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), name VARCHAR(100) NOT NULL, slug VARCHAR(60) UNIQUE NOT NULL, owner_id UUID NOT NULL REFERENCES auth.users(id) ON DELETE CASCADE, plan VARCHAR(20) NOT NULL DEFAULT 'STARTER' CHECK (plan IN ('STARTER', 'PRO')), stripe_customer_id VARCHAR(100), stripe_subscription_id VARCHAR(100), created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); -- 2. FEEDBACK POSTS TABLE CREATE TABLE feedback_posts ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), workspace_id UUID NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE, title VARCHAR(150) NOT NULL, description TEXT NOT NULL, status VARCHAR(30) NOT NULL DEFAULT 'UNDER_REVIEW' CHECK (status IN ('UNDER_REVIEW', 'PLANNED', 'IN_PROGRESS', 'COMPLETED', 'CLOSED')), vote_count INTEGER NOT NULL DEFAULT 0, author_email VARCHAR(255), author_id UUID REFERENCES auth.users(id) ON DELETE SET NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW() ); -- 3. VOTES TABLE (PREVENTS DUPLICATE VOTING) CREATE TABLE votes ( id UUID PRIMARY KEY DEFAULT uuid_generate_v4(), post_id UUID NOT NULL REFERENCES feedback_posts(id) ON DELETE CASCADE, voter_ip_or_user VARCHAR(100) NOT NULL, created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), CONSTRAINT unique_post_voter UNIQUE (post_id, voter_ip_or_user) ); -- PERFORMANCE INDEXES CREATE INDEX idx_workspaces_slug ON workspaces(slug); CREATE INDEX idx_feedback_posts_workspace_id ON feedback_posts(workspace_id); CREATE INDEX idx_feedback_posts_status ON feedback_posts(status); CREATE INDEX idx_votes_post_id ON votes(post_id); -- Enable RLS on all tables ALTER TABLE workspaces ENABLE ROW LEVEL SECURITY; ALTER TABLE feedback_posts ENABLE ROW LEVEL SECURITY; ALTER TABLE votes ENABLE ROW LEVEL SECURITY; -- WORKSPACES POLICIES CREATE POLICY "Users can view workspaces they own" ON workspaces FOR SELECT USING (auth.uid() = owner_id); CREATE POLICY "Users can create workspaces" ON workspaces FOR INSERT WITH CHECK (auth.uid() = owner_id); CREATE POLICY "Users can update their own workspaces" ON workspaces FOR UPDATE USING (auth.uid() = owner_id); -- FEEDBACK POSTS POLICIES CREATE POLICY "Public can view feedback posts for active workspaces" ON feedback_posts FOR SELECT USING (true); CREATE POLICY "Anyone can submit feedback to a workspace" ON feedback_posts FOR INSERT WITH CHECK (true); CREATE POLICY "Only workspace owners can update status" ON feedback_posts FOR UPDATE USING (EXISTS ( SELECT 1 FROM workspaces WHERE workspaces.id = feedback_posts.workspace_id AND workspaces.owner_id = auth.uid() )); { "workspaceId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "title": "Add Apple Pay support", "description": "Our customers are asking for 1-click mobile checkout via Apple Pay.", "authorEmail": "user@example.com" } { "success": true, "data": { "id": "8c5b9e02-234b-4f91-9e1b-9f4c6e3d2a10", "title": "Add Apple Pay support", "status": "UNDER_REVIEW", "voteCount": 1, "createdAt": "2026-03-01T14:32:00Z" } } { "success": false, "error": { "code": "VALIDATION_FAILED", "message": "Title must be between 5 and 150 characters." } } Set up the database layer for our Next.js 15 App Router project using TypeScript and Supabase. 1. Create a migration file containing the exact PostgreSQL DDL from Module 2: tables for `workspaces`, `feedback_posts`, and `votes` with all foreign keys, indexes, and RLS policies. 2. Create a singleton Supabase client at `src/lib/supabase/client.ts` for browser interactions and `src/lib/supabase/server.ts` using `@supabase/ssr` with cookie handling for Server Components and Server Actions. 3. Generate the TypeScript database definitions file at `src/types/database.types.ts`. Ensure zero use of 'any'. Output complete, compilable files only. Implement Supabase email magic-link and Google OAuth authentication for Next.js 15. 1. Create route handlers for auth callbacks at `src/app/auth/callback/route.ts`. 2. Build a WorkspaceContextProvider at `src/context/workspace-context.tsx` that loads the active workspace based on the URL subdomain or route param. 3. Add a Next.js middleware at `src/middleware.ts` that protects `/dashboard/*` routes, redirecting unauthenticated users to `/login`. Ensure complete error handling and zero placeholder comments. Build the backend API endpoints according to Module 3 specs. 1. Create Zod schemas for feedback post creation and voting in `src/lib/validations/post.ts`. 2. Implement `src/app/api/v1/posts/route.ts` with POST method to insert feedback items into Supabase, enforcing rate limits and input sanitization. 3. Implement `src/app/api/v1/posts/[id]/vote/route.ts` with POST method implementing duplicate vote protection using IP/User hashing. Return standard JSON responses with explicit HTTP status codes (201, 400, 409, 500). Build the frontend feedback board interface using Tailwind CSS and Lucide React icons. 1. Create atomic components in `src/components/ui/`: PostCard, UpvoteButton, StatusBadge, SkeletonLoader. 2. Implement the interactive Board component at `src/components/board/feedback-board.tsx`. 3. Use React 19 `useOptimistic` hook inside UpvoteButton to instantly increment the counter when clicked, with automatic rollback if the API returns an error. Ensure full responsiveness across mobile (375px) and desktop (1440px). Implement the Stripe billing integration for Starter ($29/mo) and Pro ($79/mo) subscriptions. 1. Build the Stripe checkout session creator Server Action in `src/app/actions/billing.ts`. 2. Implement the Stripe webhook handler at `src/app/api/v1/webhooks/stripe/route.ts` verifying the webhook signature using `stripe.webhooks.constructEvent`. 3. Handle `customer.subscription.updated` and `customer.subscription.deleted` to update the `plan` column in the `workspaces` table. 4. Wrap the post creation API with a check that blocks submission if a Starter workspace exceeds 500 posts. Output 100% complete, production-ready code.