docs: Phase A repo structure — archive, product, kebab-case
- Move copilot history and CSV to docs/archive/ - Add docs/product/ (SSP, intermediate, genre packs) and engineering/adrs/ - Rename all spaced/special-char doc paths to kebab-case - Nest competitive GTM under docs/gtm/competitive/ - Point README and NORTH_STAR at CANONICAL_STRATEGY - Leave code/ unchanged for later monorepo Phase B
This commit is contained in:
VPS admin
@@ -0,0 +1,172 @@
|
||||
# Data Flow & Privacy — geolocal.io
|
||||
|
||||
> Last updated: 2026-07-16
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
This document describes how data flows through the `geolocal.io` platform, what data we collect, how it's stored, who has access, and how we handle privacy obligations under GDPR and CCPA.
|
||||
|
||||
**Core principle:** We expose only public business data. We do not collect personal consumer data beyond what is necessary for booking transactions (handled by Cal.com and Stripe).
|
||||
|
||||
---
|
||||
|
||||
## 2. Data Collection Points
|
||||
|
||||
### 2.1 Business Data (Voluntary)
|
||||
|
||||
Businesses (or their agencies) voluntarily provide:
|
||||
|
||||
| Data | Source | Purpose |
|
||||
|------|--------|---------|
|
||||
| Business name, address, phone, website | Business owner / agency | AI discovery |
|
||||
| Operating hours | Business owner / agency | AI recommendations |
|
||||
| Services & pricing | Business owner / agency | AI recommendations |
|
||||
| Story & narrative | Business owner / agency | Differentiation in AI responses |
|
||||
| Photos & video | Business owner / agency | Visual discovery in AI |
|
||||
| Cal.com booking link | Business owner / agency | Transaction loop |
|
||||
|
||||
**Note:** This data is already publicly available on the business's website or Google Business Profile. We do not scrape it without consent.
|
||||
|
||||
### 2.2 Telemetry Data (MCP Interactions)
|
||||
|
||||
Every MCP tool call generates:
|
||||
|
||||
| Data Point | Example |
|
||||
|-----------|---------|
|
||||
| Query terms | "best mechanic in Frisco TX" |
|
||||
| Business slug referenced | "frisco-german-auto" |
|
||||
| Tool called | "get_business_info" |
|
||||
| AI platform used | ChatGPT, Gemini, Claude |
|
||||
| Timestamp | 2026-07-16T14:23:00Z |
|
||||
| Response time | 45ms |
|
||||
|
||||
### 2.3 Booking Data (via Cal.com / Stripe)
|
||||
|
||||
**We do NOT handle this directly.** Cal.com and Stripe are the providers of record. We pass booking requests to their APIs.
|
||||
|
||||
- Cal.com handles: appointment scheduling, calendar data, customer contact info
|
||||
- Stripe handles: payment processing, billing data, financial records
|
||||
|
||||
---
|
||||
|
||||
## 3. Data Storage
|
||||
|
||||
| Data Type | Where It Lives | Retention |
|
||||
|-----------|---------------|-----------|
|
||||
| Business profiles | PostgreSQL (Railway) | Until business opts out |
|
||||
| Telemetry logs | PostgreSQL + Redis (cached) | 24 months, then anonymized |
|
||||
| Photos / media | CDN (Cloudflare R2 / AWS S3) | Until business opts out |
|
||||
| Booking data | Cal.com / Stripe (external) | Per their retention policies |
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Sharing
|
||||
|
||||
| Recipient | What We Share | Why |
|
||||
|-----------|--------------|-----|
|
||||
| AI agents (ChatGPT, Gemini, etc.) | Business profile data via MCP | Core product function |
|
||||
| Partner agencies | Their client's analytics & commission data | Partner economics |
|
||||
| Chambers of Commerce | Member analytics (aggregate) | CoC dashboard |
|
||||
| Third-party data buyers (DaaS) | Anonymized telemetry only | Data-as-a-Service revenue |
|
||||
|
||||
**We never sell identifiable consumer data.** All DaaS products use aggregated, anonymized telemetry.
|
||||
|
||||
---
|
||||
|
||||
## 5. Bi-Directional MCP Data Flow
|
||||
|
||||
The "related businesses" handshake creates a bi-directional data exchange:
|
||||
|
||||
```
|
||||
AI Agent ──┐
|
||||
├──→ geolocal.io MCP Server ──→ Business Database
|
||||
│ ↓
|
||||
│ related_businesses()
|
||||
│ ↓
|
||||
│ Returns: list of related businesses
|
||||
│ ↓
|
||||
AI Agent ◄─┘───────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Verification flow:** AI agents can report data discrepancies back through the MCP protocol. We log these reports and flag business profiles for review.
|
||||
|
||||
---
|
||||
|
||||
## 6. Privacy Commitments
|
||||
|
||||
### 6.1 GDPR Principles
|
||||
- **Lawful basis:** Processing is based on business consent (they opt in) and legitimate interest (telemetry for service improvement)
|
||||
- **Data minimization:** We only collect what's needed for AI discovery and booking
|
||||
- **Right to be forgotten:** Businesses can request full data deletion
|
||||
- **Data portability:** Businesses can export their profile data at any time
|
||||
- **DPIA:** Data Protection Impact Assessment will be completed before EU data processing
|
||||
|
||||
### 6.2 CCPA Principles
|
||||
- **Notice at collection:** Clear disclosure of what data we collect
|
||||
- **Right to delete:** Businesses can request deletion of their data
|
||||
- **Right to opt out of sale:** We do not sell personal data
|
||||
- **Non-discrimination:** We do not discriminate against users who exercise their rights
|
||||
|
||||
### 6.3 What We Do NOT Do
|
||||
- We do not collect consumer PII beyond what Cal.com/Stripe handle
|
||||
- We do not track individual consumers across sessions
|
||||
- We do not use cookies for behavioral tracking
|
||||
- We do not sell individual-level data
|
||||
|
||||
---
|
||||
|
||||
## 7. Security
|
||||
|
||||
| Measure | Status |
|
||||
|---------|--------|
|
||||
| PostgreSQL connection via SSL | ✅ MVP |
|
||||
| Rate limiting on MCP endpoints | ✅ MVP |
|
||||
| Input validation (Zod schemas) | ✅ MVP |
|
||||
| OAuth 2.1 with PKCE for partner auth | Phase 2 |
|
||||
| Regular security audits | Phase 3 |
|
||||
| SOC 2 compliance | Future |
|
||||
|
||||
---
|
||||
|
||||
## 8. Incident Response
|
||||
|
||||
In the event of a data breach:
|
||||
|
||||
1. **Detect:** Automated alerts on anomalous MCP traffic patterns
|
||||
2. **Contain:** Rate-limit or disable affected endpoints
|
||||
3. **Notify:** Affected businesses notified within 72 hours (GDPR)
|
||||
4. **Remediate:** Patch vulnerability, audit for scope
|
||||
5. **Document:** Log incident, update this document
|
||||
|
||||
---
|
||||
|
||||
## 9. Data Flow Diagram
|
||||
|
||||
```
|
||||
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐
|
||||
│ Business │ │ │ │ AI Agents │
|
||||
│ Owner / │────→│ geolocal.io │←───→│ ChatGPT, │
|
||||
│ Agency │ │ MCP Server │ │ Gemini, │
|
||||
└──────────────┘ │ │ │ Claude, │
|
||||
│ ┌────────────┐ │ │ Grok │
|
||||
│ │ PostgreSQL │ │ └──────────────┘
|
||||
│ └────────────┘ │
|
||||
│ ┌────────────┐ │
|
||||
│ │ Redis │ │
|
||||
│ └────────────┘ │
|
||||
│ ┌────────────┐ │
|
||||
│ │ Telemetry │ │
|
||||
│ └────────────┘ │
|
||||
└──────┬───────────┘
|
||||
│
|
||||
┌───────┴────────┐
|
||||
│ Cal.com API │
|
||||
│ Stripe API │
|
||||
└────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
*This document must reference NORTH_STAR.md for principles. Updates require review against current privacy regulations.*
|
||||
Reference in New Issue
Block a user