# SuperLocalSEO — Claude Code Handoff Prompt ## Project Overview Build SuperLocalSEO: an enterprise-grade white-label local SEO platform for service businesses (plumbers, HVAC, electricians). The platform aggregates ranking data (BrightLocal), reviews (EmbedMyReviews), and citations into a single dashboard with automated monthly reports. **Target:** 4-6 weeks to MVP Tier 1 launch, 16 weeks to full production deployment. --- ## 📋 Complete Specification Documents Read these in order before starting. All links are public (anyone-with-link access): ### 1. **Master Project Plan** (24KB, 16-week roadmap) https://docs.google.com/document/d/1Uyb30-oq3gnMGuL8VGAOXLFE_5hdfsDs2pygXfkfWyE/edit **Contains:** - Phase 0-4 breakdown (infrastructure, MVP, features, hardening, deployment) - Complete database schema (10 tables with ERD) - Docker Compose configuration (local dev + production) - Testing strategy (unit >85%, integration >80%, E2E, regression, load tests) - API endpoint specifications - Deployment playbook (backup, disaster recovery, monitoring) - Success metrics and go-live checklist **Use this for:** Architecture decisions, task breakdown, testing requirements, deployment procedures. ### 2. **UI/UX Specifications** (16KB, pixel-perfect designs) https://docs.google.com/document/d/1J5qA10TLcrfGVtCsppS08_6eXe1oAKxHkqCflDSEJKI/edit **Contains:** - Design system (colors, typography, spacing, components) - Landing page (hero, pricing, FAQ, social proof) - Authenticated dashboard pages (home, rankings, reviews, citations, settings) - All forms, modals, empty states - Responsive breakpoints (mobile, tablet, desktop) - Accessibility requirements (WCAG 2.1 AA) - Performance targets (Lighthouse >90) **Use this for:** Frontend component development, page layouts, form design, responsive design. ### 3. **BrightLocal API Deep Dive** (Reference) https://docs.google.com/document/d/1xls8Nx2_DMzc_shwoRqoHLhe8dgvu1wm2OciiqPQe-4/edit **Contains:** - Management APIs (unlimited, included with plan) - Data APIs (metered: rankings, reviews, citations, listings) - Integration architecture - Cost analysis - Endpoint examples **Use this for:** Understanding BrightLocal API structure, data models, cost calculations. ### 4. **Review Automation White-Label Analysis** (Reference) https://docs.google.com/document/d/1Q3CM65MJtPTjfl2DdtwhY-g2QHAfYSsYHTtvPpJiWvw/edit **Contains:** - Recommended platform: EmbedMyReviews ($99/mo flat) - API capabilities and integration patterns - Comparison with alternatives (Reviewly.ai, AXL Reviews, Podium) - Implementation roadmap **Use this for:** Review management features, EmbedMyReviews integration, SMS workflow setup. ### 5. **Brand Guidelines** (Reference) https://docs.google.com/document/d/1V0r_HpvKhk0XbcoN15yojoeZ14bPtKDEaOhPqkLxaQs/edit **Contains:** - Color palette (Superman Blue #0052CC primary) - Typography (Inter font family) - Logo specifications - Messaging pillars - Brand applications (website, dashboard, reports) **Use this for:** UI design tokens, brand consistency, copy tone. --- ## 🔧 Technology Stack ### Frontend - React 18 + TypeScript - Tailwind CSS (styling) - SWR (data fetching, auto-refresh) - Redux Toolkit (state management) - Recharts (data visualization) - React Router v6 (navigation) - React Hook Form (form handling) - Zod (form validation) ### Backend - Node.js 20+ (runtime) - Express.js (API framework) - TypeScript (type safety) - PostgreSQL 15 (primary database) - Redis 7 (caching, sessions) - Bull (job queue for background tasks) - Knex.js (database migrations) - TypeORM (optional, for type-safe queries) ### Data Pipelines - n8n (workflow orchestration) - Custom Node.js worker nodes - Cron jobs (scheduled pulls) ### External APIs - BrightLocal (rankings, citations, reviews data) - EmbedMyReviews (review aggregation, webhook ingestion) - Google Business Profile API (Tier 3+) - SendGrid (email delivery) - Stripe (payments) ### Testing - Jest (unit tests) - React Testing Library (component tests) - Cypress (E2E tests) - k6 (load testing) - Supertest (API integration tests) ### DevOps & Deployment - Docker (containerization, multi-stage builds) - Docker Compose (local dev + prod orchestration) - GitHub Actions (CI/CD) - Nginx (reverse proxy) - Prometheus (metrics) - Winston (logging) - Sentry (error tracking) --- ## 📊 Unit Economics (Confirmed) **BrightLocal Costs (Confirmed Pricing):** - Growth plan: $45/mo - Citation pulls: $0.05 per source per pull - Review pulls: $0.05 per location per pull - Rankings: Included in plan **Your Refresh Strategy:** - Reviews: Every 6 hours (4 pulls/day = $6/mo per client) - Citations: Daily (10 sources = $15/mo per client) - Total BrightLocal cost per client: **$66/mo** **EmbedMyReviews Costs:** - Flat $99/mo for unlimited clients - White-label, full API access - SMS/Email BYOK (you manage Twilio) **Per-Client Economics:** - Tier 1 ($350/mo): 81% margin - Tier 2 ($700/mo): 91% margin - Tier 3 ($1,200/mo): 94% margin **At scale (50 clients):** - Revenue: $17,500/mo - Cost: $3,366/mo (BrightLocal $3,300 + EMR $99) - Profit: $14,134/mo (81% margin) --- ## 🎯 MVP Scope (Phase 1, Weeks 3-6) ### Landing Page - [ ] Hero section (headline, subheading, CTA, background image) - [ ] Value proposition cards (3 columns) - [ ] Pricing table (Tier 1-3 comparison) - [ ] FAQ section (5-6 common questions) - [ ] Footer with links and contact info - [ ] SEO optimized (meta tags, schema markup) - [ ] Mobile responsive - [ ] Analytics tracking (Segment) ### Authentication - [ ] User registration (email, password, business name) - [ ] Email verification (SendGrid) - [ ] Login/logout flows - [ ] Password reset - [ ] JWT + refresh token flow - [ ] Session management (Redis) - [ ] Role-based access (admin, agent, client) ### Onboarding - [ ] Client setup wizard (4 steps: business info, locations, keywords, integrations) - [ ] Connect BrightLocal (API key input, validation) - [ ] Connect EmbedMyReviews (API key input, validation) - [ ] Webhook registration for real-time review ingestion - [ ] Initial data pull trigger ### Tier 1 Dashboard - [ ] Dashboard home (4 overview cards + top keywords table) - Top ranking card - Reviews this week card - Citation completeness card - Monthly reports sent card - [ ] Rankings page (sortable, filterable keyword table with trend charts) - [ ] Reviews page (aggregated from all platforms, filterable by rating/platform/status) - [ ] Citations page (directory grid showing listed/NAP accuracy) - [ ] Settings page (connected accounts, disconnect options, API status) ### Backend APIs (Phase 1) - [ ] POST /auth/register, /auth/login, /auth/refresh, /auth/logout - [ ] POST /clients, GET /clients/:id, PATCH /clients/:id, DELETE /clients/:id - [ ] POST /integrations/brightlocal/connect, GET /integrations/brightlocal/status - [ ] POST /integrations/embedmyreviews/connect, GET /integrations/embedmyreviews/status - [ ] GET /rankings, GET /rankings/:clientId/trend - [ ] GET /reviews, POST /reviews/webhook (inbound webhook handler) - [ ] GET /citations/:clientId - [ ] GET /metrics/:clientId (dashboard data) - [ ] GET /health (liveness/readiness probes) ### Infrastructure (Phase 0, Weeks 1-2) - [ ] PostgreSQL schema (10 tables: users, clients, locations, integrations, rankings, reviews, citations, metrics_daily, reports, audit_logs) - [ ] Redis setup (caching, session store) - [ ] Docker Compose (local dev with all services) - [ ] GitHub Actions CI/CD (test on push, lint, coverage report) - [ ] Environment variable management (.env.example, secrets) - [ ] API server scaffold (Express + middleware + error handling) - [ ] Database migrations (Knex.js) - [ ] Health check endpoints - [ ] Logging setup (Winston to stdout, Prometheus metrics) - [ ] API response format (success/error envelopes) - [ ] Request validation (Zod schemas) - [ ] Rate limiting middleware ### Testing (All Phases) - [ ] Unit tests (Jest): >85% backend coverage - [ ] Component tests (React Testing Library): >70% frontend coverage - [ ] Integration tests (Supertest): All API endpoints - [ ] E2E tests (Cypress): Critical user journeys (register → login → view dashboard → export CSV) - [ ] Regression test suite (against previous releases) - [ ] Load tests (k6): 50 concurrent users, verify <2s p95 response time - [ ] Security tests (OWASP Top 10 checklist) --- ## 📝 GitHub Repository Setup Create a new private GitHub repo: `superlocalseo` ### Repository Structure ``` superlocalseo/ ├── README.md (project overview, tech stack, local dev setup) ├── .gitignore (Node, .env, build artifacts) ├── .github/ │ └── workflows/ │ ├── test.yml (run tests on push/PR) │ ├── lint.yml (ESLint, Prettier checks) │ └── deploy.yml (build & push Docker images on merge to main) ├── docker-compose.yml (local dev) ├── docker-compose.prod.yml (production) ├── Dockerfile (multi-stage build) ├── .env.example (environment variable template) ├── nginx.conf (reverse proxy config) ├── backend/ │ ├── package.json │ ├── tsconfig.json │ ├── jest.config.js │ ├── src/ │ │ ├── index.ts (app entry) │ │ ├── app.ts (Express setup) │ │ ├── config.ts (env vars, secrets) │ │ ├── middleware/ │ │ │ ├── auth.ts (JWT validation) │ │ │ ├── errorHandler.ts │ │ │ ├── logging.ts │ │ │ └── rateLimit.ts │ │ ├── routes/ │ │ │ ├── auth.ts │ │ │ ├── clients.ts │ │ │ ├── integrations.ts │ │ │ ├── rankings.ts │ │ │ ├── reviews.ts │ │ │ ├── citations.ts │ │ │ └── metrics.ts │ │ ├── controllers/ (business logic) │ │ ├── services/ (API integration, data transformation) │ │ ├── models/ (TypeScript interfaces) │ │ ├── db/ │ │ │ ├── migrations/ (Knex migration files) │ │ │ ├── seeds/ (test data) │ │ │ └── connection.ts │ │ ├── utils/ (helpers, validators) │ │ └── __tests__/ (test files mirroring src structure) │ └── .env (local dev secrets, NOT in git) ├── frontend/ │ ├── package.json │ ├── tsconfig.json │ ├── vite.config.ts │ ├── src/ │ │ ├── index.tsx (React entry) │ │ ├── App.tsx (routing setup) │ │ ├── pages/ │ │ │ ├── Landing.tsx (public) │ │ │ ├── Pricing.tsx (public) │ │ │ ├── Login.tsx (public) │ │ │ ├── Register.tsx (public) │ │ │ ├── Dashboard/ │ │ │ │ ├── Home.tsx │ │ │ │ ├── Rankings.tsx │ │ │ │ ├── Reviews.tsx │ │ │ │ ├── Citations.tsx │ │ │ │ └── Settings.tsx │ │ │ └── Onboarding/ │ │ │ ├── Step1.tsx (business info) │ │ │ ├── Step2.tsx (locations) │ │ │ ├── Step3.tsx (keywords) │ │ │ └── Step4.tsx (integrations) │ │ ├── components/ │ │ │ ├── Card.tsx │ │ │ ├── Button.tsx │ │ │ ├── Table.tsx │ │ │ ├── Modal.tsx │ │ │ ├── Form/ │ │ │ │ ├── Input.tsx │ │ │ │ ├── Select.tsx │ │ │ │ └── Textarea.tsx │ │ │ ├── Layout/ │ │ │ │ ├── Sidebar.tsx │ │ │ │ ├── TopBar.tsx │ │ │ │ └── MainLayout.tsx │ │ │ └── Charts/ │ │ │ ├── TrendChart.tsx │ │ │ └── SentimentBreakdown.tsx │ │ ├── hooks/ │ │ │ ├── useAuth.ts (auth context) │ │ │ ├── useFetch.ts (SWR wrapper) │ │ │ └── useForm.ts (form state) │ │ ├── store/ (Redux Toolkit) │ │ │ ├── slices/ │ │ │ │ ├── authSlice.ts │ │ │ │ ├── clientSlice.ts │ │ │ │ └── metricsSlice.ts │ │ │ └── index.ts (store setup) │ │ ├── services/ (API client functions) │ │ │ ├── api.ts (Axios instance, interceptors) │ │ │ ├── auth.ts (login, register, logout) │ │ │ ├── clients.ts │ │ │ ├── rankings.ts │ │ │ ├── reviews.ts │ │ │ └── citations.ts │ │ ├── styles/ (Tailwind config, global styles) │ │ ├── utils/ (helpers, formatters, validators) │ │ └── __tests__/ (test files) │ └── .env.local (local dev API URL, NOT in git) ├── docs/ │ ├── API.md (API documentation, OpenAPI spec) │ ├── SETUP.md (local development setup) │ ├── DEPLOYMENT.md (production deployment) │ ├── TESTING.md (test strategy and coverage) │ ├── ARCHITECTURE.md (system design, data flow) │ └── TROUBLESHOOTING.md (common issues and fixes) └── .github/ └── ISSUE_TEMPLATE/ ├── bug.md ├── feature.md └── task.md ``` --- ## 🎯 GitHub Issues to Create (Phase 0 & 1) ### Phase 0: Infrastructure (Weeks 1-2) **Epic: Infrastructure Foundation** - [ ] Task: Set up Docker Compose (Postgres, Redis, API, Web, Nginx, n8n) - [ ] Task: Create PostgreSQL schema (users, clients, locations, integrations, rankings, reviews, citations, metrics_daily, reports, audit_logs) - [ ] Task: Set up database migrations (Knex.js) - [ ] Task: Create Express server scaffold (middleware, error handling, logging) - [ ] Task: Set up GitHub Actions CI/CD (test, lint, coverage report) - [ ] Task: Implement request validation (Zod schemas) - [ ] Task: Implement JWT authentication (tokens, refresh logic) - [ ] Task: Set up health check endpoints - [ ] Task: Create API response format (success/error envelopes) - [ ] Task: Set up rate limiting middleware - [ ] Task: Write test utilities and fixtures (Faker.js, test databases) ### Phase 1: MVP Features (Weeks 3-6) **Epic: Landing Page** - [ ] Task: Build landing page layout (hero, value props, pricing, FAQ, footer) - [ ] Task: Add responsive design (mobile, tablet, desktop) - [ ] Task: Implement SEO optimizations (meta tags, schema markup) - [ ] Task: Add analytics tracking (Segment) - [ ] Task: Write Cypress E2E tests for landing page - [ ] Task: Lighthouse audit (>90 performance, >95 accessibility) **Epic: Authentication & Onboarding** - [ ] Task: Implement user registration endpoint - [ ] Task: Add email verification (SendGrid) - [ ] Task: Build login/logout UI and logic - [ ] Task: Implement password reset flow - [ ] Task: Build onboarding wizard (4 steps) - [ ] Task: Create BrightLocal connection flow - [ ] Task: Create EmbedMyReviews connection flow - [ ] Task: Register EmbedMyReviews webhook - [ ] Task: Write integration tests for auth endpoints - [ ] Task: Write E2E tests for onboarding **Epic: BrightLocal Integration** - [ ] Task: Create BrightLocal API service (client wrapper) - [ ] Task: Implement rankings pull (daily scheduled) - [ ] Task: Implement citations pull (daily scheduled) - [ ] Task: Create rankings API endpoints (GET /rankings, GET /rankings/:clientId/trend) - [ ] Task: Create citations API endpoints (GET /citations/:clientId) - [ ] Task: Cache rankings data (Redis, 24-hour TTL) - [ ] Task: Write integration tests for BrightLocal service - [ ] Task: Write unit tests for rankings/citations logic **Epic: EmbedMyReviews Integration** - [ ] Task: Create EmbedMyReviews API service (client wrapper) - [ ] Task: Implement webhook handler (POST /reviews/webhook) - [ ] Task: Implement reviews pull (6-hour scheduled) - [ ] Task: Cache reviews data (Redis, 6-hour TTL) - [ ] Task: Create reviews API endpoints (GET /reviews, GET /reviews/:clientId/sentiment) - [ ] Task: Parse and store review sentiment - [ ] Task: Write integration tests for EmbedMyReviews service - [ ] Task: Write unit tests for review sentiment logic **Epic: Dashboard — Overview** - [ ] Task: Build dashboard home page layout - [ ] Task: Create overview metric cards (top ranking, reviews, citations, reports) - [ ] Task: Create keyword table component (sortable, filterable) - [ ] Task: Integrate rankings data with dashboard - [ ] Task: Create endpoint: GET /metrics/:clientId - [ ] Task: Write component tests for dashboard cards - [ ] Task: Write E2E test for dashboard load - [ ] Task: Performance optimization (Lighthouse target: 85+) **Epic: Dashboard — Rankings Page** - [ ] Task: Build rankings page layout - [ ] Task: Create keyword table (sortable columns, pagination) - [ ] Task: Implement trend chart (Recharts line graph) - [ ] Task: Add filters (date range, keyword search) - [ ] Task: Add export to CSV - [ ] Task: Write component tests for table/chart - [ ] Task: Write E2E test for rankings page **Epic: Dashboard — Reviews Page** - [ ] Task: Build reviews page layout - [ ] Task: Create review card component - [ ] Task: Add platform filter (Google, Yelp, Trustpilot, etc.) - [ ] Task: Add rating filter - [ ] Task: Add status filter (unresponded, responded, archived) - [ ] Task: Add search functionality - [ ] Task: Display sentiment indicator - [ ] Task: Link to platform (opens in new tab) - [ ] Task: Write component tests for review cards - [ ] Task: Write E2E test for reviews page **Epic: Dashboard — Citations Page** - [ ] Task: Build citations page layout - [ ] Task: Create directory card component - [ ] Task: Display overall completeness score - [ ] Task: Show NAP accuracy per directory - [ ] Task: Create edit modal for citation updates - [ ] Task: Integrate with BrightLocal update API - [ ] Task: Write component tests for citation cards - [ ] Task: Write E2E test for citations page **Epic: Dashboard — Settings Page** - [ ] Task: Build settings page layout (tabs: account, integrations, webhooks, billing) - [ ] Task: Account tab (name, email, password change) - [ ] Task: Integrations tab (connected accounts, reconnect/disconnect) - [ ] Task: Webhooks tab (event log, test webhook button) - [ ] Task: Billing tab (plan, next billing date, CTA to upgrade) - [ ] Task: Write component tests for settings page **Epic: Testing & Quality** - [ ] Task: Write unit tests for all services (>85% coverage) - [ ] Task: Write integration tests for all API endpoints - [ ] Task: Write E2E tests for critical user journeys - [ ] Task: Write regression test suite - [ ] Task: Set up code coverage reporting (>85% backend, >70% frontend) - [ ] Task: Run Lighthouse audit (target >90 all metrics) - [ ] Task: Run OWASP Top 10 security checks - [ ] Task: Load test with k6 (50 concurrent users) --- ## 🚀 Getting Started 1. **Read the specification documents** (in order): - Master Plan (architecture, phases, database schema) - UI/UX Specs (all page layouts, forms, components) - BrightLocal Deep Dive (API structure) - Review Automation (EmbedMyReviews integration) - Brand Guidelines (design tokens, copy tone) 2. **Create GitHub repository** `superlocalseo` with the structure above 3. **Create GitHub Issues** from the list above (Phase 0 & 1) 4. **Set up local development**: ```bash git clone cp .env.example .env docker-compose up -d ``` 5. **Start Phase 0** (infrastructure foundation): - Docker Compose setup - PostgreSQL schema - Express server scaffold - GitHub Actions CI/CD - Test framework 6. **Proceed to Phase 1** once Phase 0 is complete (16 issues, 4-week timeline) --- ## 📞 Key Contacts & Configurations **External APIs (Credentials in .env, NOT in git):** - BrightLocal API Key: [Set by user] - EmbedMyReviews API Key: [Set by user] - SendGrid API Key: [Set by user] - Stripe API Key: [Set by user] - Google OAuth Client ID: [Set by user, Tier 3+] **Database:** - PostgreSQL 15: `postgres://user:password@localhost:5432/superlocalseo` - Redis 7: `redis://localhost:6379` **Deployment (Future):** - Server: IONOS AE16-128 NVMe (dedicated) - Domain: superlocalseo.com - Docker Registry: [To be set up] --- ## ✅ Success Criteria **Phase 0 Complete:** - [ ] Docker Compose working locally (all services healthy) - [ ] PostgreSQL with schema deployed - [ ] Express server responding to requests - [ ] GitHub Actions tests passing - [ ] Test framework in place (Jest, Cypress setup) **Phase 1 Complete (MVP):** - [ ] Landing page live - [ ] User registration/login working - [ ] BrightLocal integration pulling rankings daily - [ ] EmbedMyReviews integration pulling reviews every 6 hours - [ ] Dashboard displaying rankings, reviews, citations - [ ] All API endpoints tested (integration + unit tests) - [ ] E2E tests for critical paths passing - [ ] Code coverage >85% backend, >70% frontend - [ ] Lighthouse scores >90 - [ ] Ready for first Tier 1 paying customer --- **Document Links (Bookmark these):** - Master Plan: https://docs.google.com/document/d/1Uyb30-oq3gnMGuL8VGAOXLFE_5hdfsDs2pygXfkfWyE/edit - UI/UX Specs: https://docs.google.com/document/d/1J5qA10TLcrfGVtCsppS08_6eXe1oAKxHkqCflDSEJKI/edit - BrightLocal API: https://docs.google.com/document/d/1xls8Nx2_DMzc_shwoRqoHLhe8dgvu1wm2OciiqPQe-4/edit - Review Automation: https://docs.google.com/document/d/1Q3CM65MJtPTjfl2DdtwhY-g2QHAfYSsYHTtvPpJiWvw/edit - Brand Guidelines: https://docs.google.com/document/d/1V0r_HpvKhk0XbcoN15yojoeZ14bPtKDEaOhPqkLxaQs/edit --- **Ready to create the repository and start Phase 0. Let's go.**