From aaf08611876f882a32b23f55d3ac6600e8fbb0d9 Mon Sep 17 00:00:00 2001 From: Ty Date: Thu, 16 Jul 2026 20:17:16 +0000 Subject: [PATCH] Add docs/engineering/technical roadmap.md --- docs/engineering/technical roadmap.md | 216 ++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 docs/engineering/technical roadmap.md diff --git a/docs/engineering/technical roadmap.md b/docs/engineering/technical roadmap.md new file mode 100644 index 0000000..2e38aac --- /dev/null +++ b/docs/engineering/technical roadmap.md @@ -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 | \ No newline at end of file