Project Scope Guard

Productivity

Original Idea

Project Scope Guard A web app that turns change requests into mini contracts with timeline and budget deltas plus one-click approval.

Product Requirements Document (PRD): Project Scope Guard

1. Executive Summary

Project Scope Guard is a specialized B2B SaaS platform designed to eliminate "scope creep" for freelancers and digital agencies. By transforming informal change requests into legally-binding "mini-contracts," the app quantifies the impact of every modification on budget and timeline. The platform ensures that no work begins without explicit, documented client consent, thereby protecting profit margins and maintaining project transparency.

2. Problem Statement

Freelancers and agencies frequently succumb to "favor requests"—small scope additions that, in aggregate, lead to significant uncompensated labor and missed deadlines. Existing project management tools (Jira, Asana) track tasks but lack a formal legal/financial "gate" for scope changes. There is currently a friction-heavy process for drafting addendums for minor changes, leading many providers to skip the paperwork entirely and absorb the cost.

3. Goals & Success Metrics

  • Primary Goal: Reduce uncompensated "scope creep" by 90% for active users.
  • Secondary Goal: Accelerate Change Request (CR) approval time to under 24 hours.
  • Success Metrics:
    • CR Conversion Rate: Percentage of drafted CRs that reach "Approved" status.
    • Budget Recovery: Total currency value of approved deltas across the platform.
    • Time-to-Sign: Average duration between CR sending and client signature.

4. User Personas

  • Independent Freelancer (e.g., Fiona): Works solo, values speed and low overhead. Needs to send a professional-looking "mini-contract" in 60 seconds from her phone.
  • Agency Project Manager (e.g., Alex): Manages multiple high-value clients. Needs team collaboration, multi-party approvals, and integration with Jira/Asana to monitor team capacity.
  • Client Approver (e.g., Chloe): The stakeholder paying the bills. Needs a frictionless, "one-click" way to review impacts and sign without creating an account.

5. User Stories

  • As a Provider, I want to input a feature description and its cost/time delta so that I can automatically generate a legal addendum.
  • As a Provider, I want to see a dashboard showing the "Original vs. Current" budget so I can justify the total project cost to the client.
  • As a Client, I want to receive a secure link that doesn't require a password so I can approve changes instantly from my mobile device.
  • As a PM, I want an immutable audit log of who signed what and when so that we are protected during end-of-project disputes.

6. Functional Requirements

6.1. Change Request (CR) Engine

  • Delta Calculation: Users input + or - values for budget (currency) and timeline (days). The system calculates the new projected totals.
  • Template Logic: Automatic generation of legal "Mini-Contract" text based on project metadata.

6.2. One-Click Approval System

  • Stateless Signed URLs: Generation of HMAC-signed links for guest access.
  • Digital Signature: Capture of name, date, IP address, and browser fingerprint.

6.3. Audit & Compliance

  • Immutable Logs: Use of PostgreSQL triggers and hash-chaining to ensure logs cannot be altered.
  • PDF Generation: Asynchronous generation of a "Certificate of Completion" for every approved CR.

6.4. Project Dashboard

  • Visualizations: S-Curve charts showing original baseline vs. current scope impact.
  • Tenant Management: Clear separation between "Freelancer" (Personal) and "Agency" (Organization) workspaces.

7. Technical Requirements

7.1. Tech Stack (2026 Standards)

  • Frontend: Next.js v16.1.3 utilizing Turbopack and React 19.2. Styling via Tailwind CSS v4.1.18 (Oxide engine, CSS-first config).
  • Backend: Node.js with NestJS v11.1.12 (utilizing Fastify v5 for high-throughput).
  • Database: PostgreSQL via Prisma ORM v7.2.0 (Relational optimization, Rust-free client).
  • Authentication: Clerk (Multi-tenancy via Organizations).
  • Background Jobs: BullMQ with Redis for rate-limiting and PDF generation.
  • Infrastructure: Vercel (Frontend), Railway (Background Workers), Render (API).

7.2. Integrations

  • Jira/Asana: Webhook-based tracking of "Scope Creep" (unlinked tasks).
  • AWS S3: Storage of signed PDFs using @aws-sdk/lib-storage for memory-efficient streaming.
  • Postmark/Resend: Transactional email for delivery of signed URLs.

8. Data Model

Entity: Project

  • id: UUID (Primary Key)
  • tenantId: String (Clerk Org ID or User ID)
  • originalBudget: Decimal
  • currentBudget: Decimal (Computed)
  • originalDeadline: DateTime
  • status: Enum (Active, Completed, Paused)

Entity: ChangeRequest

  • id: UUID
  • projectId: UUID (FK)
  • budgetDelta: Decimal
  • timelineDeltaDays: Int
  • status: Enum (Draft, Pending, Approved, Rejected)
  • hash: String (SHA-256 for audit integrity)

Entity: ApprovalAudit (Immutable)

  • id: ULID (Sortable)
  • crId: UUID (FK)
  • signatureData: JSONB
  • previousHash: String (Hash of the previous log entry)
  • timestamp: DateTime (DB-generated NTP synchronized)

9. API Specification (Key Endpoints)

| Method | Endpoint | Description | | :--- | :--- | :--- | | POST | /projects | Create a new project container. | | POST | /cr/generate | Create a CR and generate a signed guest URL. | | GET | /approve/:token | Public endpoint for clients to view CR via HMAC validation. | | PATCH | /approve/:token | Executes the digital signature and triggers PDF generation. | | GET | /projects/:id/stats | Fetches delta metrics for dashboard visualizations. |

10. UI/UX Requirements

  • Progressive Disclosure: Use Radix UI Accordions to hide granular delta math until requested.
  • The "Five-Second Rule": The dashboard must show "Total Budget Delta" as the most prominent element.
  • Mobile-First Signing: The approval page must be optimized for thumb-driven interaction (large buttons, no-zoom inputs).
  • Semantic Feedback: Emerald Green for budget-neutral changes; Amber for budget-increasing changes.

11. Non-Functional Requirements

  • Security: HMAC-signed URLs with a 48-hour TTL. All PDF documents encrypted at rest (AES-256).
  • Performance: PDF generation must not block the API (Async worker pattern). UI response time < 100ms (Optimistic UI).
  • Accessibility: Full compliance with WCAG 2.1 AA for the client-facing approval portal.
  • Legal: Compliance with eIDAS 2.0 (EU) and ESIGN Act (US) for electronic records.

12. Out of Scope

  • Full project management suite (No kanban boards, no time tracking).
  • Direct bank transfers (Stripe integration is for deposits, not full accounting).
  • Native iOS/Android apps (PWA-only for Phase 1).

13. Risks & Mitigations

  • Risk: Clients refuse to sign digital "contracts" for small changes.
    • Mitigation: Provide a "Quick Approve" mode that simplifies the legal language for trusted partners.
  • Risk: Data tampering of audit logs.
    • Mitigation: Implement PostgreSQL triggers to block DELETE and UPDATE on the ApprovalAudit table.
  • Risk: API Rate limits on Jira/Asana.
    • Mitigation: Use BullMQ to queue and throttle external API calls.

14. Implementation Tasks

Phase 1: Project Setup

  • [ ] Initialize Next.js v16.1.3 project with Turbopack.
  • [ ] Configure Tailwind CSS v4.1.18 with CSS-first @theme configuration.
  • [ ] Set up NestJS v11.1.12 with Clerk authentication middleware.
  • [ ] Initialize Prisma v7.2.0 with PostgreSQL schema and $extends for tenant isolation.

Phase 2: Core Data & Multi-Tenancy

  • [ ] Implement nestjs-cls for request-scoped tenant tracking.
  • [ ] Build Project and Change Request CRUD operations.
  • [ ] Implement Prisma Extension to automatically filter all queries by tenant_id.
  • [ ] Create PostgreSQL triggers for immutable ApprovalAudit table.

Phase 3: Change Request Engine

  • [ ] Build CR creation UI with real-time delta math using Radix UI primitives.
  • [ ] Implement HMAC URL generation utility for guest access.
  • [ ] Create Guest Approval page with responsive "Sign and Approve" workflow.
  • [ ] Set up BullMQ for asynchronous processing of approved CRs.

Phase 4: Document & Audit Generation

  • [ ] Integrate papercraft-js for high-performance PDF generation from HTML templates.
  • [ ] Implement streaming upload to S3 using @aws-sdk/lib-storage.
  • [ ] Build the "Hash-Chain" logic to link ApprovalAudit entries cryptographically.
  • [ ] Implement email notification worker using Resend/Postmark.

Phase 5: Dashboard & Integrations

  • [ ] Create Dashboard visualizations using Tremor (Area charts for budget deltas).
  • [ ] Implement Jira/Asana webhook receivers to flag unlinked "Scope Creep."
  • [ ] Add "White-label" settings for Agency branding (Logo/Colors).
  • [ ] Conduct accessibility audit (WCAG 2.1 AA) on the client signing portal.