# SuperLocalSEO — Documentation Feedback & Action Items

**Date:** 2026-05-12  
**Reviewer:** Conductor  
**Status:** Awaiting corrections

---

## Critical Missing Docs

### 1. API_ENDPOINTS.md
**Priority:** 🔴 BLOCKING  
**Effort:** 2 hours  
**Description:** Create REST API reference with HTTP method, path, request body, response schema, auth requirements, and error codes for all endpoints.

**Include:**
- `GET /api/rankings?locationId=&days=30`
- `POST /api/reviews/respond`
- `GET /api/metrics/visibility`
- All CRUD endpoints for locations, keywords, competitors
- Report generation endpoints
- Integration endpoints (BrightLocal sync, EmbedMyReviews webhook)

---

### 2. DEPLOYMENT.md
**Priority:** 🔴 BLOCKING  
**Effort:** 3 hours  
**Description:** Production deployment flow to IONOS AE16-128 dedicated server.

**Must cover:**
- Docker Compose setup (dev + prod variants)
- Database migration strategy (Knex.js auto-run, manual, or versioned?)
- Environment variables (.env.example template)
- SSL/TLS setup (Certbot + Nginx)
- Health checks (systemd, Kubernetes probes, or manual monitoring?)
- Database backup/recovery strategy (snapshots, WAL archiving?)
- Scaling considerations

---

### 3. TESTING_STRATEGY.md
**Priority:** 🔴 BLOCKING  
**Effort:** 2 hours  
**Description:** Comprehensive test plan.

**Must define:**
- Unit test coverage targets (>80%?)
- What's being tested: auth flows, scoring logic, API endpoints, job queues
- E2E test scope: happy path for signup → add location → view rankings
- Integration test strategy: mocking vs. fixtures for BrightLocal/EmbedMyReviews APIs
- CI/CD flow: GitHub Actions, coverage enforcement, deployment gates
- Load testing approach (k6 or similar)

---

### 4. INTEGRATIONS.md
**Priority:** 🟡 IMPORTANT  
**Effort:** 2 hours  
**Description:** Matrix of all third-party APIs.

**Must include table:**
| API | MVP/Phase | Rate Limit | Fallback Strategy | Key Management |
|-----|-----------|-----------|-------------------|-----------------|
| BrightLocal | MVP | Specify | Exponential backoff queue? | .env only? AWS Secrets? |
| EmbedMyReviews | MVP | Specify | Graceful degrade | ? |
| Stripe | MVP | Specify | Webhook retry? | ? |
| Google OAuth | MVP | Specify | Manual flow? | ? |
| Facebook Graph | Phase 2 | Specify | Defer to Phase 2 | ? |
| Resend | MVP | Specify | Fallback SMTP? | ? |
| Anthropic Claude | MVP | Specify | Fallback template? | ? |

---

## High-Priority Clarifications Needed

### 1. Billing Logic (PRODUCT.md + Backend)
**Questions:**
- How does trial → paid conversion flow work?
- Can users downgrade mid-trial?
- Do they see restricted features after trial expires, or full access until payment fails?
- Prorating for mid-month location adds: $150/12 × 15 days?
- Who handles billing support escalation? (Stripe hosted checkout or custom page?)

**Action:** Add "Billing Logic" subsection to PRODUCT.md explaining trial flow, downgrades, prorating, support paths.

---

### 2. Error Handling & Resilience (ARCHITECTURE.md)
**Questions:**
- BrightLocal returns 429 (rate limit) → Exponential backoff in job queue?
- DB connection pool exhausted → 503 response?
- Stripe webhook delivery fails → Retry with exponential backoff? How many retries?
- Report generation crashes halfway → Mark as `status = 'failed'` with error reason?

**Action:** Add "Error Handling & Resilience" section to ARCHITECTURE.md covering all failure modes.

---

### 3. Stripe Integration Details (Billing & Webhooks)
**Questions:**
- How do subscription upgrades work? (New subscription + proration credit, or update existing?)
- Location add-ons: separate line items on the subscription, or manual invoice supplements?
- Webhook handler scope: subscription state changes, payment failures, refunds, disputes?
- Do you use Stripe test mode for dev/staging? (Assume yes, clarify.)
- Webhook signature validation implemented?

**Action:** Add Stripe integration detail to INTEGRATIONS.md or create separate BILLING.md.

---

### 4. QR Code Tracking (Feature #9 in PRODUCT.md)
**Questions:**
- Schema location: `qr_codes` table? `qr_scans` table? Where is it defined?
- Scan tracking: timestamp + IP + user agent + referrer?
- Privacy implications: IP logging = GDPR issue if you have EU clients. Are you compliant?
- Is this MVP or Phase 2? (PRODUCT.md doesn't specify timeline.)

**Action:** Add QR code schema to ARCHITECTURE.md or clarify in PRODUCT.md that it's Phase 2.

---

### 5. RBAC Matrix (PRODUCT.md + Backend)
**Questions:**
- Are there roles beyond "admin" and "client"?
- Can a Tier 3 account have multiple users with different roles?
- What can a "client" role do that an "admin" cannot?
- Can an admin share a location with another admin account?
- Any per-location role restrictions? (e.g., "rep can only see assigned locations")

**Action:** Add "Roles & Permissions" section with a matrix: Role | Permissions | Scope.

---

### 6. BrightLocal API Tier & Pricing (Business Critical)
**Status:** ⚠️ UNCONFIRMED  
**Impact:** Affects unit economics + feature timeline  
**Question:** API_GAPS.md assumes Management API paid tier (citation submission, reputation manager, GBP sync). What's the upgrade cost? Does it break unit economics?

**Action:** Lock in BrightLocal pricing with contact ASAP. Update unit economics if needed.

---

## Doc-Specific Issues

### PRODUCT.md

| Issue | Severity | Action |
|-------|----------|--------|
| Feature #9 (QR Code) has no implementation timeline | 🟡 | Clarify: MVP or Phase 2? |
| "All tiers include every feature — no feature gating" contradicts Tier 3 add-ons | 🟡 | Clarify which features require Tier 2+ |
| Competitor benchmarking mentions "Google rating" but reviews come from 100+ platforms | 🟡 | Clarify: Google-only, or aggregated? |
| "14-day free trial, no credit card" contradicts Stripe requirement for trial auto-convert | 🟡 | Clarify trial → paid flow |
| Unit economics assume 10 clients @ Tier 1 = $3,500/mo, but BL cost is $45/mo flat + per-pull | 🟡 | Recalculate with accurate BL pricing |
| **Missing:** "Limitations" section (max keywords per location, review sync latency, data retention, report gen time) | 🟡 | Add section explaining known constraints |

### ARCHITECTURE.md

| Issue | Severity | Action |
|-------|----------|--------|
| No error handling strategy described | 🔴 | Add "Resilience & Error Handling" section |
| Redis usage unclear: JWT blocklist only, or rate limiting + sessions too? | 🟡 | Clarify Redis role in architecture |
| DB connection pooling: Knex defaults to 2 connections | 🟡 | Confirm pool size adequate for production (likely 10–20) |
| No secrets management strategy (BL key, Stripe key, Google OAuth, etc.) | 🔴 | Clarify: .env only? AWS Secrets Manager? Vault? |
| Backup & disaster recovery not mentioned | 🔴 | Add section: PostgreSQL backup strategy, recovery SLA, snapshots |
| No monitoring/alerting thresholds mentioned | 🟡 | You mention Sentry + Prometheus but no alert rules (error rate >5%?, latency >500ms?, etc.) |

### API_GAPS.md

| Issue | Severity | Action |
|-------|----------|--------|
| Assumes BrightLocal paid plan for Management API features (citation, reputation, GBP) | 🟡 | Lock in with Harry — what's the cost? Does it break unit economics? |
| EMR-1 (client provisioning) marked LOW but critical for agency tier positioning | 🔴 | Re-prioritize to HIGH if this is a go-to-market lever |
| BL-13 (agency BL client provisioning) is LOW but gates EMR-1 | 🔴 | Clarify dependency: can you launch agency tier without it? |
| BL-1 (geo-grid) marked IMPLEMENTED but schema migration not run yet | 🟡 | Clarify: code complete but not deployed? Still in development? |
| No feature flag / A/B test strategy for post-launch rollouts | 🟡 | How do you roll out BL-1 geo-grid? All customers at once, or gradual? |

---

## Quick Wins (10 hours to unblock development)

| Priority | Doc | Effort | Owner |
|----------|-----|--------|-------|
| 🔴 CRITICAL | API_ENDPOINTS.md | 2h | Backend lead |
| 🔴 CRITICAL | DEPLOYMENT.md | 3h | DevOps / Backend lead |
| 🔴 CRITICAL | TESTING_STRATEGY.md | 2h | QA / Backend lead |
| 🟡 IMPORTANT | INTEGRATIONS.md | 2h | Backend lead |
| 🟡 IMPORTANT | PRODUCT.md → add "Limitations" + fix billing clarity | 1h | Product |
| 🟡 IMPORTANT | ARCHITECTURE.md → add "Error Handling", "Secrets", "Backup" | 2h | Backend lead |

---

## Blocking Items Before Phase 0

- [ ] API_ENDPOINTS.md created and published
- [ ] DEPLOYMENT.md created and tested (dry-run on IONOS box)
- [ ] TESTING_STRATEGY.md created with CI/CD pipeline defined
- [ ] BrightLocal Management API pricing locked in with contact
- [ ] Billing logic documented and finalized
- [ ] RBAC roles and permissions matrix defined
- [ ] Stripe integration flow documented
- [ ] QR code feature scope clarified (MVP vs Phase 2)

---

## Notes

- Both PRODUCT.md and ARCHITECTURE.md are solid foundations — these clarifications are refinements, not rewrites.
- The 10-hour estimate assumes content already exists in code/decisions; you're mostly documenting + formalizing.
- API_GAPS.md is excellent planning; once the 4 blocking docs are done, development can proceed without roadblocks.