Ty_Tech/geolocal-io
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Phase A repo structure — archive, product, kebab-case

Browse Source 
- 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
2026-07-18 05:23:39 +00:00
parent 36853f3bab
commit 3f9c86f823
32 changed files with 250 additions and 121 deletions
Download Patch File Download Diff File Expand all files Collapse all files
NORTH_STAR.md
+7 -3
View File
@@ -85,8 +85,12 @@ If we wait, the incumbents win. The agentic economy is being built today, and wh
---
## What's Next?
## What's next?
This document is our compass. It anchors product decisions, fundraising conversations, and go-to-market execution.
This document is a short compass. The full operating strategy is:
Now the real question: **What's the first sprint?** What can we build in the next 30 days that proves the model and starts building the data network?
**[docs/strategy/CANONICAL_STRATEGY.md](./docs/strategy/CANONICAL_STRATEGY.md)** (final draft)
Product detail: [docs/product/](./docs/product/). Historical exploration: [docs/archive/](./docs/archive/).
Near-term execution question: what can we ship in the next 30 days that proves Model 1 (HTTP MCP + portal spine + real pilot endpoints) and starts a destination pilot conversation?
README.md
+50 -60
View File
@@ -1,86 +1,76 @@
# geolocal.io
> AI-native infrastructure for local business discovery, storytelling, visuals, and booking via MCP. Powers the long tail of independent SMBs ignored by big platforms.
AI-native infrastructure for local business discovery, storytelling, visuals, and booking via MCP. Powers the long tail of independent service businesses that big platforms do not serve cleanly in the agent era.
## What Is This?
## Start here
`geolocal.io` makes local service businesses discoverable, bookable, and payable in the agentic AI economy.
1. **[Canonical Strategy](./docs/strategy/CANONICAL_STRATEGY.md)** — operating truth (final draft)
2. **[North Star](./NORTH_STAR.md)** — short compass
3. **[Product overview](./docs/product/overview.md)** — what we build
We do this by:
## What this is
- **Hosting a multi-tenant MCP server** that exposes rich, structured business data (story, visuals, services, pricing, availability) to any AI agent.
- **Providing a simple JSON pointer** (`/.well-known/mcp-server`) that any business can add to their website to connect to our hosted MCP server—no coding required.
- **Enabling a complete transaction loop** by integrating with Cal.com for booking and Stripe for payment capture.
- **Building a partner-first distribution engine** by working through agencies, SEO consultants, and Chambers of Commerce who already serve these businesses.
- **Creating a self-reinforcing data network** where AI agents provide verification and competitive intelligence data through our "related businesses" handshake.
geolocal.io makes local service businesses discoverable, bookable, and measurable inside AI assistants by:
We are not a destination site. We are an invisible, critical layer of infrastructure that powers the agentic economy's discovery of local businesses.
- Hosting a **multi-tenant MCP** agents can call for structured business truth
- Giving businesses a **simple pointer** on their own site (no servers for them to run)
- Providing a **Self-Service Portal** so owners can see and test how AI understands them
- Working with **tourism boards, chambers, and partners** for distribution
- Integrating **Cal.com** and **Stripe** for booking and payment — we orchestrate, we do not rebuild those categories
## The Problem We Solve
We are not a consumer destination site. We are infrastructure.
- **45% of consumers** now use AI tools to find local businesses—up from just **6% one year earlier**.
- **ChatGPT recommends just 1.2% of local businesses**, according to SOCi's 2026 Local Visibility Index.
- **AI is now the third most-used business discovery channel**, behind only Google and Facebook.
## Who should read what
The major platforms (Google, Yelp, OpenAI) are building MCP infrastructure to serve their own data. They are **not** building infrastructure to serve the businesses themselves. We bridge that gap.
### Partners (agencies, SEO, chambers)
## Quick Start
1. [Ideal customer profile](./docs/gtm/ideal-customer-profile.md)
2. [Channel strategy](./docs/gtm/channel-strategy.md) and [Sales and marketing](./docs/gtm/sales-and-marketing.md)
3. [Partner one-pager](./docs/gtm/partner-one-pager.md)
### For Partners (Agencies, SEO Consultants, Chambers)
### Investors
1. Read the **[Ideal Customer Profile](./docs/gtm/Ideal%20Customer%20Profile.md)** to understand who we target.
2. Review the **[Channel Strategy](./docs/gtm/ChannelStrategy.md)** and **[Sales and Marketing](./docs/gtm/Sales%20and%20marketing.md)** for the playbook.
3. Use the **[Partner One-Pager](./docs/gtm/Partner%20One-Pager.md)** as your sell-sheet.
1. [Canonical Strategy](./docs/strategy/CANONICAL_STRATEGY.md)
2. [Market data and analysis](./docs/investors/market-data-and-analysis.md)
3. [Business and financial model](./docs/investors/business-and-financial-model.md) and [Moats and risks](./docs/gtm/competitive/moats-and-risks.md)
### For Investors
### Engineering
1. Read the **[North Star](./NORTH_STAR.md)** document for our vision and principles.
2. Review the **[Market Data & Analysis](./docs/investors/Market%20Data%20&%20Analysis.md)** for the opportunity size.
3. Explore the **[Business and Financial Model](./docs/investors/Business%20and%20financial%20model.md)** and **[Competitive Moats & Risks](./docs/gtm/Competitive%20moats%20and%20risks.md)** for our defensible position.
1. [Canonical Strategy](./docs/strategy/CANONICAL_STRATEGY.md) priorities
2. [Technical roadmap](./docs/engineering/technical-roadmap.md)
3. [code/](./code/) — MCP MVP (TypeScript)
4. [ADRs](./docs/engineering/adrs/)
### For Developers & Engineers
## Repository map (Phase A)
1. Read the **[Technical Roadmap](./docs/engineering/technical%20roadmap.md)** for our phased implementation plan.
2. Explore the **[code/](./code/)** directory for the MCP server implementation.
3. See **[package.json](./code/package.json)** for dependencies and scripts.
## Repository Structure
```
```text
geolocal-io/
├── NORTH_STAR.md # Single source of truth for vision & principles
├── README.md # This file
├── code/ # MCP server implementation (TypeScript)
│ ├── src/
│ │ ├── index.ts # Server entry point (stdio transport)
│ │ ├── mcp-server.ts # Tool registration (5 MCP tools)
│ │ ├── config.ts # Environment configuration
│ │ ├── manifest-generator.ts # /.well-known/mcp-server JSON
│ │ ├── db/ # PostgreSQL schema + seed data
│ │ ├── tools/ # get_business_info, get_hours, etc.
│ │ └── routes/ # Multi-tenant gateway
│ ├── package.json
│ ├── tsconfig.json
│ ├── Dockerfile
│ └── railway.json
├── NORTH_STAR.md
├── README.md
├── code/ # MCP server MVP (later → apps/mcp-gateway)
└── docs/
├── investors/ # Market data, financial model
├── gtm/ # ICP, channel strategy, partner one-pager
├── engineering/ # Technical roadmap
└── legal/ # Data flow, partnership agreement, IP notes
├── strategy/ # CANONICAL_STRATEGY.md (operating truth)
├── product/ # SSP, intermediate, genre packs
├── gtm/ # channels, sales, competitive/
├── investors/
├── engineering/ # roadmap + adrs/
├── legal/
└── archive/ # historical exploration only
```
Later monorepo phases add `apps/`, `packages/`, `genres/`, and `infra/` without changing the docs contract above.
## Status
| Area | Status |
| :--- | :--- |
| **Strategy & Vision** | ✅ Complete |
| **Market Data & Analysis** | ✅ Complete |
| **Competitive Intelligence** | ✅ Complete |
| **Business & Financial Model** | ✅ Complete |
| **Product & Technical Roadmap** | ✅ Complete |
| **GTM Strategy** | ✅ Complete |
| **Legal & Compliance** | ✅ Complete |
| **MCP Server (code/)** | ✅ MVP — 5 tools, TypeScript, Railway-ready |
|------|--------|
| **Canonical strategy** | Final draft |
| **Market / GTM / legal docs** | Present (some GTM still pre-strategy framing) |
| **Product docs** | Scaffolded |
| **MCP server (`code/`)** | MVP — 5 tools, TypeScript, Railway-ready |
| **Self-Service Portal** | Specified; not built |
| **HTTP multi-tenant gateway** | Priority 0 |
## Doc governance
If a document conflicts with [docs/strategy/CANONICAL_STRATEGY.md](./docs/strategy/CANONICAL_STRATEGY.md), fix the conflict on purpose. Historical exploration lives in [docs/archive/](./docs/archive/), not in operating GTM.
docs/README.md
+13
View File
@@ -0,0 +1,13 @@
# Documentation
| Folder | Role |
|--------|------|
| [strategy/](./strategy/) | **Operating truth** — start with CANONICAL_STRATEGY.md |
| [product/](./product/) | SSP, intermediate, genre packs |
| [gtm/](./gtm/) | Channels, sales, competitive |
| [investors/](./investors/) | Market and financial packaging |
| [engineering/](./engineering/) | Roadmap and ADRs |
| [legal/](./legal/) | Privacy, IP, partnership skeletons |
| [archive/](./archive/) | Historical only — not operating docs |
Governance: if two docs disagree, resolve against strategy or deliberately change strategy.
docs/archive/README.md
+10
View File
@@ -0,0 +1,10 @@
# Archive
Historical materials kept for context. **Not operating documentation.**
| File | What it is |
|------|------------|
| [geolocal-copilot-conversation.md](./geolocal-copilot-conversation.md) | Early exploration conversation that informed the strategy |
| [copilot-activity-history.csv](./copilot-activity-history.csv) | Activity export from that session |
Operating truth lives in [../strategy/CANONICAL_STRATEGY.md](../strategy/CANONICAL_STRATEGY.md).
docs/copilot-activity-history.csv → docs/archive/copilot-activity-history.csv
View File
Can't render this file because it is too large.
docs/geolocal-copilot-conversation.md → docs/archive/geolocal-copilot-conversation.md
View File
docs/engineering/README.md
+8 -18
View File
@@ -1,22 +1,12 @@
# Engineering — geolocal.io
# Engineering
Architecture, technical roadmap, and implementation.
Architecture, roadmap, and implementation notes.
## Files
| Doc | Purpose |
|-----|---------|
| [technical-roadmap.md](./technical-roadmap.md) | Phased technical plan (align with strategy when they diverge) |
| [adrs/](./adrs/) | Architecture decision records |
| File | Description |
|------|-------------|
| [Technical Roadmap](./technical%20roadmap.md) | 12-week phased plan: MVP → V1 → Scale |
**Operating priorities** come from [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§10). When this folder and the strategy disagree, fix one of them deliberately.
## Code
The MCP server implementation lives in the repo root [`code/`](../../code/) directory:
- **`src/index.ts`** — Server entry point (stdio transport)
- **`src/mcp-server.ts`** — Tool registration (5 MCP tools)
- **`src/tools/`** — Individual tool implementations
- **`src/db/`** — PostgreSQL schema + seed data
- **`src/manifest-generator.ts`** — `/.well-known/mcp-server` JSON manifest
- **`railway.json`** + **`Dockerfile`** — Deployment config
Every technical decision must trace back to [NORTH_STAR.md](../../NORTH_STAR.md).
Current implementation lives in `code/` (MCP MVP). A later monorepo phase moves that to `apps/mcp-gateway`.
docs/engineering/adrs/README.md
+26
View File
@@ -0,0 +1,26 @@
# Architecture Decision Records (ADRs)
Short, dated decisions so we do not re-litigate the same choices.
## Format
Each ADR: `NNNN-short-title.md`
```markdown
# NNNN — Title
**Status:** proposed | accepted | superseded
**Date:** YYYY-MM-DD
## Context
## Decision
## Consequences
```
## Index
| ADR | Title | Status |
|-----|-------|--------|
| — | *(none yet)* | — |
Candidates worth writing soon: HTTP vs stdio for production MCP; Cal.com orchestration vs rebuild booking; monorepo layout (Phase B).
docs/engineering/technical roadmap.md → docs/engineering/technical-roadmap.md
View File
docs/gtm/README.md
+11 -13
View File
@@ -1,16 +1,14 @@
# GTM — geolocal.io
# Go-to-market
Partner-first go-to-market strategy and collateral.
Channel, sales, and competitive materials. Must describe the company in [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) — not a thinner or different product.
## Files
| Doc | Purpose |
|-----|---------|
| [ideal-customer-profile.md](./ideal-customer-profile.md) | Who we target |
| [channel-strategy.md](./channel-strategy.md) | Distribution channels |
| [sales-and-marketing.md](./sales-and-marketing.md) | Sales and marketing playbook |
| [partner-one-pager.md](./partner-one-pager.md) | Partner sell-sheet |
| [competitive/intelligence.md](./competitive/intelligence.md) | Competitor landscape |
| [competitive/moats-and-risks.md](./competitive/moats-and-risks.md) | Moats and risks |
| File | Description |
|------|-------------|
| [Ideal Customer Profile](./Ideal%20Customer%20Profile.md) | Who we target: agencies, SEO consultants, CoCs |
| [Channel Strategy](./ChannelStrategy.md) | 3-pronged distribution: agencies, vertical subdomains, SEO |
| [Sales and Marketing](./Sales%20and%20marketing.md) | Playbook, messaging, funnel |
| [Competitive Intelligence](./Competitive%20Intelligence.md) | Competitor mapping and positioning |
| [Competitive Moats & Risks](./Competitive%20moats%20and%20risks.md) | Defensibility and threat analysis |
| [Partner One-Pager](./Partner%20One-Pager.md) | Agency sell-sheet (ready to send) |
All content here must align with [NORTH_STAR.md](../../NORTH_STAR.md).
**Note:** Some GTM docs still reflect older partner-dashboard-first framing. Treat strategy as source of truth until those docs are revised.
docs/gtm/ChannelStrategy.md → docs/gtm/channel-strategy.md
View File
docs/gtm/competitive/README.md
+8
View File
@@ -0,0 +1,8 @@
# Competitive
| Doc | Purpose |
|-----|---------|
| [intelligence.md](./intelligence.md) | Competitor landscape |
| [moats-and-risks.md](./moats-and-risks.md) | Moats and risks |
Parent index: [../README.md](../README.md).
docs/gtm/Competitive Intelligence.md → docs/gtm/competitive/intelligence.md
View File
docs/gtm/Competitive moats and risks.md → docs/gtm/competitive/moats-and-risks.md
+1 -1
View File
@@ -2,7 +2,7 @@
## 0. Relationship to the Competitive Intelligence Dossier
This document is the strategic companion to the **Competitive Intelligence Dossier**, which profiles the key players in the local business AI discovery space (Yelp, Google, Pie, Mainstreet, Apify, and others). This analysis assumes familiarity with that landscape and focuses on:
This document is the strategic companion to the **[Competitive intelligence](./intelligence.md)** dossier, which profiles the key players in the local business AI discovery space (Yelp, Google, Pie, Mainstreet, Apify, and others). This analysis assumes familiarity with that landscape and focuses on:
1. **Our defensible positions:** What makes `geolocal.io` hard to replicate
2. **The unseen strength:** Why first-mover advantage and critical mass are the real moats
docs/gtm/Ideal Customer Profile.md → docs/gtm/ideal-customer-profile.md
View File
docs/gtm/Partner One-Pager.md → docs/gtm/partner-one-pager.md
+1 -1
View File
@@ -103,4 +103,4 @@ Or reply to this one-pager — we'll get you set up and your first client live i
---
> *Full market data and citations: [Market Data & Analysis](../investors/Market%20Data%20&%20Analysis.md)*
> *Full market data and citations: [Market data and analysis](../investors/market-data-and-analysis.md)*
docs/gtm/Sales and marketing.md → docs/gtm/sales-and-marketing.md
+2 -2
View File
@@ -222,5 +222,5 @@ With `geolocal.io`:
---
> *Full market data and citations: [Market Data & Analysis](../investors/Market%20Data%20&%20Analysis.md)*
> *Full competitive analysis: [Competitive Intelligence](./Competitive%20Intelligence.md)*
> *Full market data and citations: [Market data and analysis](../investors/market-data-and-analysis.md)*
> *Full competitive analysis: [Competitive intelligence](./competitive/intelligence.md)*
docs/investors/README.md
+6 -10
View File
@@ -1,12 +1,8 @@
# Investors — geolocal.io
# Investors
Pitch materials, market sizing, financial model.
External packaging of market and financial material. Align narrative with [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md).
## Files
| File | Description |
|------|-------------|
| [Market Data & Analysis](./Market%20Data%20&%20Analysis.md) | $98.8B TAM, consumer AI adoption trends |
| [Business and Financial Model](./Business%20and%20financial%20model.md) | Revenue model, unit economics, projections |
Align everything to [NORTH_STAR.md](../../NORTH_STAR.md).
| Doc | Purpose |
|-----|---------|
| [market-data-and-analysis.md](./market-data-and-analysis.md) | Market size and adoption signals |
| [business-and-financial-model.md](./business-and-financial-model.md) | Business and financial model |
docs/investors/Business and financial model.md → docs/investors/business-and-financial-model.md
View File
docs/investors/Market Data & Analysis.md → docs/investors/market-data-and-analysis.md
View File
docs/legal/README.md
+8 -10
View File
@@ -1,13 +1,11 @@
# Legal — geolocal.io
# Legal
Compliance, data flow, partnership agreements, IP notes.
Lightweight legal and compliance notes for pilots and product.
## Files
| Doc | Purpose |
|-----|---------|
| [data-flow-and-privacy.md](./data-flow-and-privacy.md) | Data flow and privacy |
| [ip-notes.md](./ip-notes.md) | IP notes |
| [partnership-agreement-skeleton.md](./partnership-agreement-skeleton.md) | Partnership agreement skeleton |
| File | Description |
|------|-------------|
| [Data Flow & Privacy](./Data%20Flow%20&%20Privacy.md) | Data collection, storage, sharing, GDPR/CCPA |
| [Partnership Agreement Skeleton](./Partnership%20Agreement%20Skeleton.md) | Template for agency/CoC partnerships |
| [IP Notes](./IP%20Notes.md) | Trademark, telemetry ownership, open-source strategy |
Must reference [NORTH_STAR.md](../../NORTH_STAR.md) for principles.
Not a substitute for counsel. Strategy §13 calls for tourism pilot terms, business ToS, and basic telemetry privacy next.
docs/legal/Data Flow & Privacy.md → docs/legal/data-flow-and-privacy.md
View File
docs/legal/IP Notes.md → docs/legal/ip-notes.md
View File
docs/legal/Partnership Agreement Skeleton.md → docs/legal/partnership-agreement-skeleton.md
View File
docs/product/README.md
+13
View File
@@ -0,0 +1,13 @@
# Product
Product definitions for what we build and sell. Aligns with [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md).
| Doc | Purpose |
|-----|---------|
| [overview.md](./overview.md) | Product map across the four models |
| [ssp.md](./ssp.md) | Self-Service Portal (primary SMB experience) |
| [intermediate.md](./intermediate.md) | Tourism boards, chambers, visitor bureaus |
| [genre-packs.md](./genre-packs.md) | Vertical primitives strategy |
| [use-cases/](./use-cases/) | Canonical use cases (to be filled) |
These folders start thin on purpose. Expand them as decisions lock; do not reintroduce conflicting product stories in GTM-only docs.
docs/product/genre-packs.md
+18
View File
@@ -0,0 +1,18 @@
# Genre packs
Generic business fields are scaffolding. Durable differentiation is **genre-specific primitives** — structured tools and schemas that match how a vertical actually works.
## Planned early packs
- Auto repair
- Beauty
- Home services
- Tourism activity (especially with destination pilots)
## Detail source
[Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§5.3).
## Repo note (future)
Genre packs will live under top-level `genres/` in a later monorepo phase. Product intent is documented here first.
docs/product/intermediate.md
+15
View File
@@ -0,0 +1,15 @@
# Intermediate product (tourism, chambers, visitor bureaus)
Model 2: destinations and membership organizations as discovery nodes.
## Intent
One intermediate relationship should bring many member endpoints online. Boards get an aggregating MCP, member onboarding (via SSP patterns), and a simple dashboard of hits and category demand. Funding often sits in lodging-tax or destination marketing budgets.
## Detail source
[Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§4 Model 2, §7 GTM wedge).
## Build status
Not implemented. Engineering Priority 1 after Model 1 spine is real.
docs/product/overview.md
+20
View File
@@ -0,0 +1,20 @@
# Product overview
geolocal.io ships **AI-readiness infrastructure** for local services: hosted multi-tenant MCP, a discovery pointer on the business site, the Self-Service Portal, intermediate (destination/chamber) surfaces, and later telemetry and graph products.
See [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) sections 4–5 for the full product definition and the four business models.
## Surfaces
| Surface | Audience | Status |
|---------|----------|--------|
| MCP gateway | AI agents | MVP in `code/` (stdio); HTTP is Priority 0 |
| Self-Service Portal | SMB owners | Specified in strategy; not built |
| Intermediate dashboard | Tourism boards / chambers | Specified; not built |
| Partner surfaces | Agencies / SEO | Distribution; after core attach |
## Related docs
- [ssp.md](./ssp.md)
- [intermediate.md](./intermediate.md)
- [genre-packs.md](./genre-packs.md)
docs/product/ssp.md
+17
View File
@@ -0,0 +1,17 @@
# Self-Service Portal (SSP)
Primary product experience for individual local businesses (Model 1).
## Intent
Owners should feel the value before they pay: genre-aware onboarding, site scrape reflection, a live simulation of an AI recommending and booking them, pointer install, in-browser preflight against their MCP, optimization guidance, optional partner handoff, and ongoing reports.
The portal chat UI is a **test harness** for how *external* AI assistants will interpret the business — not a customer-facing chatbot we sell as the product.
## Detail source
Full narrative and priorities: [Canonical Strategy](../strategy/CANONICAL_STRATEGY.md) (§5 Self-Service Portal, §10 priorities).
## Build status
Not implemented. Engineering Priority 0 includes the portal spine once HTTP MCP is underway.
docs/product/use-cases/README.md
+5
View File
@@ -0,0 +1,5 @@
# Use cases
Canonical use cases (Bob’s Garage, destination board, etc.) will land here as structured product specs.
Until then, narrative examples remain in the strategy and archive; do not treat the archive as the product spec.
docs/strategy/CANONICAL_STRATEGY.md
+4 -3
View File
@@ -295,13 +295,14 @@ Run self-serve SMB in parallel. Prefer short pilot contracts over perfect enterp
| Document | Job |
|----------|-----|
| `docs/geolocal-copilot-conversation.md` | Historical exploration archive — useful context, not the operating manual |
| `docs/archive/` | Historical exploration only — not the operating manual |
| **`docs/strategy/CANONICAL_STRATEGY.md` (this file)** | **Operating strategy the team rallies around** |
| `NORTH_STAR.md` | Short compass; must stay consistent with this file |
| `docs/product/*` | Product surfaces (SSP, intermediate, genre packs) |
| `docs/gtm/*` | Execution detail for channels and sales; must describe this company, not a different one |
| `docs/investors/*` | External packaging of this strategy |
| `docs/engineering/*` | Build plan for the priorities above |
| `code/` | Implementation of Priority 0 |
| `docs/engineering/*` | Build plan and ADRs for the priorities above |
| `code/` | Implementation of Priority 0 (later monorepo: `apps/mcp-gateway`) |
If two documents disagree, either this file changes on purpose or the other document changes. Silence is how the project fractures again.
docs/strategy/README.md
+7
View File
@@ -0,0 +1,7 @@
# Strategy
| Doc | Role |
|-----|------|
| **[CANONICAL_STRATEGY.md](./CANONICAL_STRATEGY.md)** | Final-draft operating strategy — team plans, builds, and sells against this |
If another doc conflicts with the canonical strategy, update that doc or deliberately revise the strategy. Do not leave both live.