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,216 @@
|
||||
# Product & Technical Roadmap
|
||||
|
||||
## 1. The Guiding Principle
|
||||
|
||||
`geolocal.io` is an **infrastructure platform**, not a destination site.
|
||||
|
||||
Everything we build must follow a single principle: **make it dead simple for a partner to deploy an MCP endpoint for a local business, and make that endpoint compelling enough that AI agents prefer it.**
|
||||
|
||||
This means:
|
||||
- **No coding required** for the business or partner to set up
|
||||
- **Centralized MCP hosting** (multi-tenant) with a simple JSON pointer for each business
|
||||
- **Rich, structured data** that gives AI agents a reason to trust and use our endpoints
|
||||
- **A self-reinforcing network** where more data attracts more agents, which generates more data
|
||||
|
||||
---
|
||||
|
||||
## 2. Technical Architecture Overview
|
||||
|
||||
### 2.1 High-Level System Components
|
||||
|
||||
| Component | Description | Technology Stack |
|
||||
| :--- | :--- | :--- |
|
||||
| **MCP Gateway** | Multi-tenant router that directs requests to the correct business MCP server | Node.js/TypeScript, FastMCP framework |
|
||||
| **Business MCP Server** | Hosts the actual MCP tools for each business; dynamically generated from database | TypeScript, MCP SDK |
|
||||
| **Business Database** | Stores business profiles, metadata, structured content, and telemetry | PostgreSQL, Supabase / Railway |
|
||||
| **JSON Manifest Generator** | Generates the `/.well-known/mcp-server` JSON file for each business | Static file generation |
|
||||
| **Partner Dashboard** | Agency-facing portal for onboarding, management, and analytics | React/Next.js, Tailwind |
|
||||
| **CoC Dashboard** | Chamber-facing portal for member management and analytics | React/Next.js, Tailwind |
|
||||
| **Business Dashboard** | SMB-facing portal for profile management and analytics | React/Next.js, Tailwind |
|
||||
| **Telemetry Pipeline** | Captures and processes MCP interaction data for analytics and DaaS | Postgres, Redis, Webhooks |
|
||||
|
||||
### 2.2 Data Flow
|
||||
AI Agent → MCP Gateway → Business MCP Server → Database / Cal.com / Stripe
|
||||
↓
|
||||
Telemetry Pipeline → Dashboards / Analytics
|
||||
|
||||
---
|
||||
|
||||
## 3. Technical Enablers: MCP Patterns You Can Leverage
|
||||
|
||||
### 3.1 Orchestration Pattern
|
||||
|
||||
Multiple MCP servers can be composed into a single endpoint, exposing tools from multiple sources to the AI as a unified interface.
|
||||
|
||||
**Relevance to you:** Your gateway will handle orchestration, enabling you to pull in tools from Cal.com's MCP or your own proprietary tools seamlessly.
|
||||
|
||||
### 3.2 Deployment Modes
|
||||
|
||||
| Mode | Description | Best For |
|
||||
| :--- | :--- | :--- |
|
||||
| **Managed-Shared** | Single MCP server instance serves multiple users simultaneously | **Your scenario:** Centralizing data from many businesses into one server |
|
||||
| **Managed-Dedicated** | Each business gets their own container instance | High-security or high-traffic businesses |
|
||||
| **Remote** | MCP server hosted by a third party; you just get a URL | Cal.com's MCP server integration |
|
||||
|
||||
### 3.3 Transport Options
|
||||
|
||||
| Transport | Description | Best For |
|
||||
| :--- | :--- | :--- |
|
||||
| **SSE (Server-Sent Events)** | Simple, server-push capable, easier for older clients | Quick start, simple use cases |
|
||||
| **Streamable HTTP** | More efficient, supports larger payloads, recommended for production | **Recommended for your platform** |
|
||||
|
||||
### 3.4 Tool Design Best Practices
|
||||
|
||||
| Best Practice | Example |
|
||||
| :--- | :--- |
|
||||
| **Granular tools** | `get_business_info`, `check_availability`, `book_appointment` (not one giant `do_everything` tool) |
|
||||
| **Clear descriptions** | Descriptions help the AI decide which tool to call |
|
||||
| **Structured inputs** | Use JSON Schema for parameters |
|
||||
| **Rich outputs** | Include links to visuals, booking confirmation, etc. |
|
||||
|
||||
---
|
||||
|
||||
## 4. Phase 1: MVP (90 Days)
|
||||
|
||||
### 4.1 MVP Scope
|
||||
|
||||
| Component | Features | Priority |
|
||||
| :--- | :--- | :--- |
|
||||
| **MCP Gateway** | Single multi-tenant MCP endpoint; basic routing by tenant | Must-have |
|
||||
| **Business Database** | Store: business name, address, hours, services, description, photos URLs, Cal.com link | Must-have |
|
||||
| **MCP Tools** | `get_business_info`, `get_hours`, `get_services`, `get_booking_link` | Must-have |
|
||||
| **Cal.com Integration** | Redirect to Cal.com booking page (Phase 1: no deep API integration) | Must-have |
|
||||
| **JSON Manifest Generator** | Generate `/.well-known/mcp-server` file for each business | Must-have |
|
||||
| **Partner Dashboard** | Partner sign-up, client onboarding (add client → generate manifest) | Must-have |
|
||||
| **Telemetry** | Basic logging: request counts, tool calls, response times | Nice-to-have |
|
||||
|
||||
### 4.2 Implementation Plan: 90-Day Sprint
|
||||
|
||||
| Week | Deliverable |
|
||||
| :--- | :--- |
|
||||
| **1-2** | Stand up PostgreSQL database; define schema; build business CRUD API |
|
||||
| **3-4** | Build MCP server using TypeScript + MCP SDK; implement first tools (get_business_info, get_hours) |
|
||||
| **5-6** | Implement JSON manifest generator; test discovery flow |
|
||||
| **7-8** | Build Partner Dashboard (sign-up, client management, manifest download) |
|
||||
| **9-10** | Integrate Cal.com (redirect); test end-to-end flow |
|
||||
| **11-12** | Onboard 10 pilot businesses; collect feedback; iterate |
|
||||
|
||||
### 4.3 Hosting Infrastructure Decision
|
||||
|
||||
| Option | Pros | Cons | Recommended? |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Railway** | One-click deployment, free tier, simple | Less control, scaling limits | ✅ **Recommended for MVP** |
|
||||
| **CreateOS** | Native MCP auto-discovery, persistent Postgres, marketplace | Newer platform, smaller community | Consider for production |
|
||||
| **AWS ECS / Fargate** | Full control, enterprise-grade | Operational overhead, more complex | Later stage |
|
||||
| **Google Cloud Run** | Serverless, scales well | Cold starts, less MCP-specific tooling | Later stage |
|
||||
|
||||
**Recommendation:** Start with **Railway** for MVP speed. Plan to migrate to **CreateOS** or **AWS** for production scale.
|
||||
|
||||
---
|
||||
|
||||
## 5. Phase 2: Scale & Features (180 Days)
|
||||
|
||||
### 5.1 Expanded Scope
|
||||
|
||||
| Component | Features |
|
||||
| :--- | :--- |
|
||||
| **MCP Tools (Expanded)** | `check_availability` (via Cal.com API), `book_appointment` (via Cal.com API) |
|
||||
| **Deep Cal.com Integration** | Direct API integration (not just redirect); availability checks; booking creation |
|
||||
| **Stripe Integration** | Payment capture for deposits; account creation for businesses |
|
||||
| **Rich Content Layer** | Story, owner bio, high-quality photos, video; structured for AI extraction |
|
||||
| **Related Businesses Tool** | `get_related_businesses` handshake; competitive intelligence capture |
|
||||
| **MCP Gateway (Advanced)** | Rate limiting, authentication, OAuth support |
|
||||
| **Business Dashboard** | SMB-facing portal for profile management; basic analytics |
|
||||
| **Partner Dashboard (Expanded)** | White-label support; client analytics; commission tracking |
|
||||
| **CoC Dashboard** | Member management; group analytics; lead reporting |
|
||||
| **Telemetry Pipeline** | Structured logging; event tracking; basic analytics dashboards |
|
||||
|
||||
### 5.2 Implementation Plan
|
||||
|
||||
| Phase | Month | Deliverable |
|
||||
| :--- | :--- | :--- |
|
||||
| **5.2.1** | **4** | Deep Cal.com API integration; Stripe payment capture; expanded MCP tools |
|
||||
| **5.2.2** | **5** | Related Businesses tool; telemetry pipeline; basic analytics |
|
||||
| **5.2.3** | **6** | Business Dashboard; CoC Dashboard; white-label support |
|
||||
|
||||
---
|
||||
|
||||
## 6. Phase 3: Ecosystem & Monetization (360 Days)
|
||||
|
||||
### 6.1 Expanded Scope
|
||||
|
||||
| Component | Features |
|
||||
| :--- | :--- |
|
||||
| **Data-as-a-Service (DaaS)** | Anonymized telemetry data for licensing; AI Local Demand Index; competitive benchmarks |
|
||||
| **Plugin Ecosystem** | WordPress plugin; Webflow app; Framer plugin |
|
||||
| **Chamber Partnership Portal** | White-labeled CoC onboarding; member analytics; lead reporting |
|
||||
| **Multi-Vertical Support** | Auto repair, beauty, home services, wellness, etc. |
|
||||
| **Developer API** | Public API for custom MCP server development |
|
||||
| **OAuth & Authorization** | OAuth 2.1 with Dynamic Client Registration (DCR) for partner integrations |
|
||||
| **Advanced Telemetry** | Agent behavior analysis; market trend identification; anomaly detection |
|
||||
| **Feedback Loop** | Verification tools; AI agent conflict reporting; automated data correction |
|
||||
|
||||
### 6.2 Implementation Plan
|
||||
|
||||
| Phase | Month | Deliverable |
|
||||
| :--- | :--- | :--- |
|
||||
| **6.2.1** | **7-9** | WordPress plugin; Webflow app; Chamber Partnership Portal |
|
||||
| **6.2.2** | **10-12** | DaaS product launch; multi-vertical support; OAuth/authorization layer |
|
||||
| **6.2.3** | **12+** | Feedback loop; advanced telemetry; public developer API |
|
||||
|
||||
---
|
||||
|
||||
## 7. Technology Stack Recommendations
|
||||
|
||||
| Layer | Technology | Rationale |
|
||||
| :--- | :--- | :--- |
|
||||
| **Backend** | Node.js / TypeScript | MCP SDK is TypeScript-first; large ecosystem |
|
||||
| **API Framework** | FastMCP | High-performance, minimal boilerplate for MCP servers |
|
||||
| **Database** | PostgreSQL (Supabase / Railway) | Reliable, JSON support, hosted options |
|
||||
| **Frontend** | React / Next.js | Modern, fast, server-side rendering for dashboards |
|
||||
| **Hosting** | Railway (MVP) → CreateOS / AWS (prod) | Balance of speed, cost, and control |
|
||||
| **Cache** | Redis | For rate limiting, session management |
|
||||
| **Analytics** | Postgres / Custom | You control the telemetry; build your own analytics layer |
|
||||
| **Payment** | Stripe | Mature, API-first, handles deposits and subscriptions |
|
||||
| **Booking** | Cal.com API | MCP-aware, structured API, booking + payment integration |
|
||||
|
||||
---
|
||||
|
||||
## 8. Key Technical Risks & Mitigation
|
||||
|
||||
| Risk | Mitigation |
|
||||
| :--- | :--- |
|
||||
| **MCP protocol changes rapidly** | Follow the official MCP GitHub; use stable SDK versions; subscribe to release notes |
|
||||
| **Cal.com API changes** | Build a small abstraction layer; use Cal.com's official MCP server where possible |
|
||||
| **Scalability of multi-tenant MCP** | Design for horizontal scaling; use Redis for session management; monitor performance |
|
||||
| **Latency from AI agents** | Optimize tool responses; use caching; prioritize frequent tools |
|
||||
| **Security of OAuth flows** | Use OAuth 2.1 with PKCE; follow MCP's security recommendations; regular audits |
|
||||
| **Data privacy concerns** | Design privacy-first; avoid storing sensitive PII; comply with GDPR/CCPA |
|
||||
| **Telemetry volume growth** | Use cost-effective storage; batch writes; use data compression |
|
||||
|
||||
---
|
||||
|
||||
## 9. Technical Guiding Principles
|
||||
|
||||
| Principle | Why It Matters |
|
||||
| :--- | :--- |
|
||||
| **Standard-first** | Follow MCP standards; avoid proprietary customizations |
|
||||
| **Simple over complex** | Start simple; add complexity only when needed |
|
||||
| **Observable by design** | Log everything; make telemetry a first-class feature |
|
||||
| **Security by default** | OAuth, rate limiting, data validation from day one |
|
||||
| **Partner-first UX** | Dashboards and onboarding should prioritize partner ease over "consumer polish" |
|
||||
| **Data ownership** | Capture telemetry; build a data moat |
|
||||
|
||||
---
|
||||
|
||||
## 10. Citation Table
|
||||
|
||||
| ID | Source |
|
||||
| :--- | :--- |
|
||||
| [1] | Anthropic, "Model Context Protocol GitHub Repository," 2024-2026 |
|
||||
| [2] | MCP Documentation, "Server Deployment Modes," 2026 |
|
||||
| [3] | MCP Documentation, "Transport Options," 2026 |
|
||||
| [4] | MCP Documentation, "Tool Design Best Practices," 2026 |
|
||||
| [5] | Railway, "MCP Server Deployment Guide," 2026 |
|
||||
| [6] | CreateOS, "MCP Server Hosting Documentation," 2026 |
|
||||
| [7] | Cal.com, "MCP Server Documentation," 2026 |
|
||||
Reference in New Issue
Block a user