Product Requirements Document (PRD) for Customers.dev

1. Overview

1.1 Purpose

Customers.dev is a comprehensive customer management platform designed to streamline customer data handling, list management, and service integrations. It provides a dashboard, marketing site, REST API, and demo site to enable developers and businesses to manage customer data efficiently. The main site (customers.dev) uses Clerk for authentication, integrated as a satellite auth to do.dev. The REST API is built using Convex HTTP Actions, providing a serverless, scalable API infrastructure. All components are deployed on Vercel and Convex Cloud for simplicity and automatic scaling.

1.2 Scope

The project encompasses:

• Main Site (customers.dev): A Next.js-based dashboard and marketing site with Clerk authentication tied to do.dev, deployed on Vercel.
• REST API: Convex HTTP Actions providing serverless REST API endpoints for customer and list management.
• Private NPM Package: A publishable NPM package for API access.
• Demo Site: A public GitHub-hosted example showcasing API usage, deployed on Vercel.
• Data Storage: Convex for secure, scalable real-time data management.
• Monorepo Structure: Managed with Turborepo for efficient development.

2. Goals and Objectives

• Provide a user-friendly dashboard for managing customers and lists.
• Offer a secure, scalable REST API for customer data operations using Convex HTTP Actions.
• Enable developers to integrate with the API via a private NPM package.
• Demonstrate API usage through a public demo site.
• Ensure secure authentication using Clerk, integrated with do.dev.
• Ensure data security and scalability using Convex's real-time database and serverless infrastructure.
• Streamline deployments with Vercel (frontend) and Convex Cloud (API/data).
• Streamline development with a monorepo architecture.

3. Stakeholders

• Product Team: Defines features and requirements.
• Developers: Build and maintain the platform.
• Customers: Businesses and developers using the platform.
• Marketing Team: Promotes the platform via the marketing site.

4. Functional Requirements

4.1 Main Site (customers.dev)

• Authentication:
  • Use Clerk for user authentication (login, logout, registration).
  • Implement satellite authentication linked to do.dev, allowing single sign-on (SSO) or shared user sessions.
  • Support OAuth providers (e.g., Google, GitHub) via Clerk for seamless login.
• Dashboard:
  • View, add, edit, and delete customers.
  • Create and manage customer lists (e.g., waitlists).
  • Display list-based analytics (e.g., list size, activity).
• Marketing Site:
  • Showcase features, pricing, and documentation.
  • Include a "Get Started" CTA linking to the dashboard or demo site.
  • Clerk-powered login visible on marketing pages for dashboard access.
• Tech Stack:
  • Next.js with TypeScript for frontend and server-side logic.
  • Tailwind CSS for styling.
  • Responsive design for mobile and desktop.
  • Clerk SDK for authentication integration.
• Deployment: Deployed on Vercel for automatic scaling and global CDN.

4.2 REST API (Convex HTTP Actions)

• Framework: Convex HTTP Actions for serverless REST API endpoints.
• Authentication: API key-based authentication managed through Convex, separate from Clerk user authentication.
• Endpoints:
  • POST /api/customers: Create a new customer (name, email, phone, etc.).
  • GET /api/customers/:id: Retrieve customer details.
  • PUT /api/customers/:id: Update customer details.
  • DELETE /api/customers/:id: Delete a customer.
  • POST /api/lists: Create a customer list (e.g., waitlist).
  • GET /api/lists/:id: Retrieve list details and associated customers.
  • PUT /api/lists/:id: Update list details.
  • DELETE /api/lists/:id: Delete a list.
  • POST /api/lists/:id/customers: Add customers to a list.
  • DELETE /api/lists/:id/customers/:customerId: Remove customers from a list.
• Data Validation: Enforce required fields (e.g., email format, unique IDs) using Convex validators.
• Rate Limiting: Implement per-user rate limits using Convex actions and database tracking.
• Documentation: API documentation hosted alongside the marketing site.
• Deployment: Convex HTTP Actions deployed automatically via Convex CLI to Convex Cloud infrastructure.

4.3 Private NPM Package

• Purpose: Provide a client library for API interaction.
• Features:
  • TypeScript support with full type definitions.
  • Methods for all API endpoints (create, read, update, delete for customers and lists).
  • Authentication handling (API key or token management, independent of Clerk).
  • Error handling and retry logic.
• Access: Published to a private NPM registry, accessible via authentication.
• Versioning: Semantic versioning for compatibility.

4.4 Demo Site

• Purpose: Showcase API usage and integration process.
• Implementation:
  • A standalone Next.js app hosted on GitHub.
  • Includes example code for authenticating and calling Convex HTTP API endpoints (using API keys).
  • Demonstrates customer and list management (e.g., creating a waitlist).
• Accessibility: Public repository with clear README and setup instructions.
• Tech Stack: Next.js, TypeScript, Tailwind CSS, and the private NPM package.
• Deployment: Deployed on Vercel for automatic scaling and global CDN.

4.5 Data Storage

• Backend: Convex for real-time, scalable data storage.
• Schema:
  • Customers: Fields include id, name, email, phone, createdAt, updatedAt.
  • Lists: Fields include id, name, description, createdAt, updatedAt, customerIds (array of customer IDs).
• Access Control: Role-based access to ensure data privacy, integrated with Clerk user data for dashboard access.
• Project: Dedicated private Convex project for customers.dev.

4.6 Monorepo Structure

• Tool: Turborepo for managing multiple packages/apps.
• Structure:
  • apps/web: Next.js app for customers.dev (dashboard + marketing, with Clerk).
  • apps/web/convex: Convex backend with HTTP Actions for REST API, queries, mutations, and schema.
  • apps/demo-site: Next.js demo site (future).
  • packages/api-client: Private NPM package for API access (future).
  • packages/ui: Shared UI components (ShadCN-based).
  • packages/typescript-config: Shared TypeScript configurations.
• Benefits: Code sharing, consistent tooling, streamlined CI/CD, and unified Convex backend.

5. Non-Functional Requirements

• Performance:
  • API response time: <200ms for 95% of requests under normal load (Convex HTTP Actions).
  • Dashboard page load: <2s for initial render (leveraging Vercel's CDN).
  • Clerk authentication: <1s for login/signup.
  • Real-time updates: <100ms for Convex reactive queries.
• Scalability:
  • Handle up to 10,000 customers and 1,000 lists initially.
  • Convex ensures automatic horizontal scaling for data and API.
  • Vercel handles automatic scaling for main and demo sites.
  • Serverless architecture scales to zero when idle, reducing costs.
• Security:
  • Encrypt sensitive data (e.g., customer emails) at rest in Convex.
  • Use HTTPS for all API and site communication.
  • Leverage Clerk's secure authentication practices (e.g., JWT, session management).
  • API key management and validation through Convex.
  • Implement OWASP best practices (e.g., input validation, XSS protection).
• Reliability:
  • API uptime: 99.9% with Convex Cloud's managed infrastructure.
  • Vercel ensures 99.9% uptime for main and demo sites.
  • Convex handles data consistency, automatic backups, and point-in-time recovery.
  • Clerk ensures reliable authentication services.
• Maintainability:
  • TypeScript for type safety across frontend and backend.
  • Monorepo for code organization and shared packages.
  • Automated tests (unit, integration) for API, dashboard, and Clerk integration.
  • Convex schema versioning and migration support.

6. User Stories

• As a business user, I want to log into the dashboard using my do.dev credentials via Clerk to manage customers and lists.
• As a developer, I want to use the NPM package to integrate customer and list management into my app.
• As a potential customer, I want to explore the marketing site and sign up via Clerk to understand the platform's value.
• As a developer learning the platform, I want to use the demo site to see example API integrations for customer and list management.
• As an admin, I want secure, reliable data storage and authentication to protect customer information.
• As a developer, I want the API to be automatically deployed and scaled without managing servers.

7. Technical Architecture

• Frontend:
  • Next.js 15.4+ with TypeScript and Tailwind CSS v4.
  • Clerk SDK for authentication, configured as satellite auth to do.dev.
  • ShadCN UI component library via shared @workspace/ui package.
  • Deployed on Vercel leveraging automatic scaling, edge functions, and global CDN.
• Backend:
  • Convex Cloud: Serverless backend-as-a-service for all data and API needs.
  • HTTP Actions: REST API endpoints via Convex HTTP Actions.
  • Queries/Mutations: Real-time data operations with automatic caching and invalidation.
  • Schema: TypeScript-defined Convex schema for type-safe data operations.
  • Authentication: Convex auth integration with Clerk for user session validation.
• Monorepo:
  • Turborepo with pnpm for package management.
  • Shared ESLint/Biome, and TypeScript configurations.
  • Workspace packages for UI components and TypeScript configs.
• CI/CD:
  • GitHub Actions for automated testing, linting, and deployment.
  • Vercel automatic deployments on push to main branch.
  • Convex automatic deployments via convex deploy command.
  • Test Clerk authentication flows in CI.

8. Milestones and Timeline

• Phase 1 (3 weeks): ✅ COMPLETED
  • Set up monorepo with Turborepo.
  • Configure Convex project with schema for customers and lists.
  • Integrate Clerk satellite authentication with do.dev.
  • Set up basic Next.js site with dashboard structure.
  • Deploy to Vercel with Convex Cloud backend.
• Phase 2 (4 weeks): CURRENT
  • Develop Convex HTTP Actions for REST API (CRUD for customers and lists).
  • Implement API key authentication system in Convex.
  • Build dashboard UI for customer and list management.
  • Add marketing pages and documentation.
  • Implement role-based access control.
• Phase 3 (3 weeks):
  • Create private NPM package for API client.
  • Develop demo site with example integrations.
  • Publish demo site to GitHub and deploy to Vercel.
  • Add comprehensive API documentation.
• Phase 4 (2 weeks):
  • Perform end-to-end testing across all components.
  • Optimize performance and bundle sizes.
  • Security audit and penetration testing.
  • Production launch of customers.dev.

9. Success Metrics

• User Engagement: 100 active dashboard users within 3 months of launch.
• API Usage: 1,000 API calls/day within 6 months.
• Demo Site: 500 GitHub stars for the demo repo within 6 months.
• Authentication Success: 95% successful login rate via Clerk within 1s.
• Reliability: 99.9% API uptime with Convex Cloud; 99.9% site uptime with Vercel.
• Performance: Meet non-functional requirements for response time and real-time updates.
• Customer Satisfaction: NPS score of 8+ from initial users.
• Developer Experience: Average API integration time <2 hours with NPM package.

10. Risks and Mitigations

• Risk: Clerk integration complexity with do.dev satellite auth.
  • Mitigation: Satellite auth is already working in current codebase; maintain comprehensive documentation.
• Risk: API security vulnerabilities.
  • Mitigation: Implement OWASP best practices, API key rotation, rate limiting, and regular security audits.
• Risk: Monorepo complexity.
  • Mitigation: Use Turborepo's caching and task orchestration for efficiency; maintain clear documentation.
• Risk: Convex learning curve for team.
  • Mitigation: Convex already implemented with working schema; leverage excellent Convex documentation and community.
• Risk: Convex HTTP Actions limitations for complex API needs.
  • Mitigation: Evaluate during Phase 2; Convex HTTP Actions support most REST patterns; can add custom Node.js endpoints if needed.
• Risk: Vendor lock-in with Convex Cloud.
  • Mitigation: Convex is open-source; can self-host if needed; TypeScript schema is portable.

11. Future Considerations

• Add GraphQL API via Convex alongside REST HTTP Actions.
• Expand list services (e.g., automated email campaigns for waitlists via integrations).
• Integrate analytics for deeper customer insights (Convex analytics or external tools).
• Support multi-tenancy for enterprise users with organization-based data isolation.
• Explore Clerk's advanced features (e.g., organizations, custom user metadata, SSO).
• Implement Convex cron jobs for scheduled tasks (e.g., automated reports, data cleanup).
• Add webhooks for real-time event notifications to customer applications.
• Develop mobile app using React Native with shared API client.