Commit 5a7b90
2026-03-13 01:51:34 Claude (Dev): [mcp] Port PRD phases to wiki| /dev/null .. design/prd phases.md | |
| @@ 0,0 1,186 @@ | |
| + | This page is part of the **wikibot.io PRD** (Product Requirements Document). See also: [[Design/PRD Overview]], [[Design/PRD Data Model]], [[Design/PRD Auth]], [[Design/PRD Operations]]. |
| + | |
| + | --- |
| + | |
| + | ## Implementation Sequence |
| + | |
| + | ### Phase 0: EFS + Lambda + Auth proof of concept |
| + | |
| + | Validate the two core technical risks: git on EFS via Lambda, and MCP OAuth via WorkOS. |
| + | |
| + | **EFS + Lambda:** |
| + | 1. Pulumi project scaffold (VPC, subnets, security groups, VPC endpoints for DynamoDB + S3) |
| + | 2. EFS filesystem + Lambda with VPC config and EFS mount |
| + | 3. X-Ray tracing enabled on Lambda and API Gateway |
| + | 4. Create a bare git repo on EFS |
| + | 5. Lambda function that mounts EFS, commits a file, reads it back |
| + | 6. Measure via X-Ray: cold start latency (including VPC attach), git read latency, git write latency |
| + | 7. Test concurrent reads and writes from multiple Lambda invocations |
| + | 8. Set up AWS Budgets billing alarm ($50/mo threshold) |
| + | |
| + | **WorkOS + MCP OAuth:** |
| + | 9. Set up WorkOS AuthKit with Google OAuth (one provider is enough to validate) |
| + | 10. Prototype FastMCP + WorkOS integration on Lambda — serve an MCP endpoint with OAuth 2.1 |
| + | 11. Test Claude.ai connecting to the MCP endpoint via OAuth flow |
| + | 12. Verify raw provider `sub` retrieval via WorkOS API (especially Apple — if available) |
| + | |
| + | **Exit criteria**: |
| + | - EFS: page read <500ms warm, page write <1s warm, cold start <5s total |
| + | - MCP OAuth: Claude.ai can authenticate and call an MCP tool via WorkOS OAuth flow on Lambda |
| + | |
| + | --- |
| + | |
| + | ### FREE TIER (Phases 1–4) |
| + | |
| + | ### Phase 1: Single-user serverless wiki |
| + | |
| + | Port the existing stack to the chosen platform. No multi-tenancy yet — one user, one wiki, running serverless instead of a VPS. |
| + | |
| + | 1. Pulumi project scaffold (dev stack, base resources) |
| + | 2. Adapt Otterwiki for Lambda (Mangum adapter, EFS mount for repo storage) |
| + | 3. Git storage on EFS (bare repos at /mnt/efs/{user}/{wiki}/repo.git) |
| + | 4. Port REST API plugin (unchanged logic, new storage backend) |
| + | 5. Port MCP server (Streamable HTTP instead of SSE) |
| + | 6. Routing and TLS |
| + | 7. Deploy and test end-to-end |
| + | |
| + | ### Phase 2: Multi-tenancy and auth |
| + | |
| + | 1. Auth provider setup (WorkOS AuthKit + FastMCP integration) |
| + | 2. DynamoDB tables (Users, Wikis, ACLs) |
| + | 3. Management API (create/list/delete wikis, token generation, ACLs) |
| + | 4. Per-wiki routing and user namespace (`{username}.wikibot.io`) |
| + | 5. ACL enforcement in middleware |
| + | 6. Wiki bootstrap template (Home, Meta/Wiki Usage Guide, Meta/Page Template) |
| + | 7. CLI tool for wiki management (`wiki create`, etc.) |
| + | |
| + | ### Phase 3: Frontend |
| + | |
| + | 1. SPA scaffold (auth flow, dashboard, wiki settings) |
| + | 2. Static hosting (S3 + CloudFront) |
| + | 3. MCP connection instructions page (copy-paste `claude mcp add` command) |
| + | 4. Public wiki toggle |
| + | |
| + | ### Phase 4: Git remote access and launch prep |
| + | |
| + | 1. Hosted Git remote (read-only clone/pull for free tier) |
| + | 2. Rate limiting |
| + | 3. Monitoring and alerting (Pulumi-managed) |
| + | 4. Backup strategy (AWS Backup for EFS, DynamoDB PITR) |
| + | 5. Landing page and docs |
| + | |
| + | **Free tier is shippable after Phase 4.** |
| + | |
| + | --- |
| + | |
| + | ### PREMIUM TIER (Phases 5+) |
| + | |
| + | ### Phase 5: Stripe integration and premium gating |
| + | |
| + | 1. Stripe subscription setup ($4.99/month) |
| + | 2. Tier enforcement in middleware (wiki count, page count, feature flags) |
| + | 3. Upgrade/downgrade flows in frontend |
| + | 4. Webhook handling for subscription lifecycle |
| + | |
| + | ### Phase 6: Semantic search |
| + | |
| + | 1. Embedding pipeline (Bedrock titan-embed-text-v2) |
| + | 2. FAISS index build, stored on EFS alongside repo |
| + | 3. Async reindex on page write (SQS → Lambda) |
| + | 4. Wire into MCP and API handlers |
| + | 5. Gate behind premium tier check |
| + | |
| + | ### Phase 7: Premium features |
| + | |
| + | 1. Read/write Git remote access (push/pull) |
| + | 2. External Git sync (bidirectional, scheduled) |
| + | 3. Custom domains (TLS cert provisioning, DNS validation) |
| + | 4. Custom wiki styling (CSS upload/editor) |
| + | 5. Create wiki from remote template repo |
| + | 6. REST API access |
| + | 7. Expanded limits (wikis, pages, collaborators, attachments) |
| + | |
| + | --- |
| + | |
| + | ## Frontend |
| + | |
| + | ### Technology |
| + | |
| + | Static SPA (React or Svelte) deployed to S3 + CloudFront. Communicates with backend via API Gateway. |
| + | |
| + | ### Screens |
| + | |
| + | **Public:** |
| + | - Landing / marketing page |
| + | - Login / signup (OAuth provider selection: Google, GitHub, Microsoft, Apple) |
| + | |
| + | **Authenticated user:** |
| + | - Dashboard: list of my wikis, create new wiki button |
| + | - Wiki settings: rename, regenerate MCP token, manage collaborators, connect external Git remote, delete |
| + | - MCP connection instructions: copy-paste `claude mcp add` command with token |
| + | |
| + | **Admin (stretch):** |
| + | - User list, usage metrics, tier management |
| + | |
| + | ### MVP scope |
| + | |
| + | The frontend can start as a CLI tool (`wiki create`, `wiki list`, `wiki token`, `wiki grant`) that calls the management API directly. Build the SPA when the workflow is validated. |
| + | |
| + | --- |
| + | |
| + | ## API Surface |
| + | |
| + | ### Management API (new) |
| + | |
| + | | Method | Endpoint | Description | |
| + | |--------|----------|-------------| |
| + | | `POST` | `/admin/wikis` | Create a wiki. Body: `{slug, display_name}`. Initializes bare repo on EFS, creates DynamoDB records. Returns MCP token (shown once). | |
| + | | `GET` | `/admin/wikis` | List caller's wikis. Returns array of `{slug, display_name, page_count, last_accessed}`. | |
| + | | `GET` | `/admin/wikis/{slug}` | Wiki details including MCP endpoint URL and connection instructions. | |
| + | | `DELETE` | `/admin/wikis/{slug}` | Delete wiki (EFS repo, DynamoDB records, FAISS index). Requires confirmation. | |
| + | | `POST` | `/admin/wikis/{slug}/token` | Regenerate MCP bearer token. Invalidates old token. Returns new token (shown once). | |
| + | | `POST` | `/admin/wikis/{slug}/acl` | Grant access. Body: `{email, role}`. Looks up user by email in DynamoDB. | |
| + | | `DELETE` | `/admin/wikis/{slug}/acl/{user_sub}` | Revoke access. | |
| + | | `GET` | `/admin/wikis/{slug}/acl` | List access grants. | |
| + | |
| + | ### Wiki API (existing, adapted) |
| + | |
| + | Same endpoints as the existing `otterwiki-api`, but scoped under `/{user}/{wiki}/api/v1/`. Authentication via OAuth JWT or MCP bearer token instead of a single API key. Includes full-text search (free tier) and semantic search (premium tier). |
| + | |
| + | ### MCP endpoint (existing, adapted) |
| + | |
| + | Same tools as the existing `otterwiki-mcp`, exposed at `/{user}/{wiki}/mcp`. Authentication via bearer token or OAuth. |
| + | |
| + | --- |
| + | |
| + | ## Freemium Tiers |
| + | |
| + | | Feature | Free | Premium | |
| + | |---------|------|---------| |
| + | | Wikis | 1 | 10 (configurable) | |
| + | | Pages per wiki | 500 | Unlimited | |
| + | | Full-text search | Yes (built into Otterwiki) | Yes | |
| + | | Semantic search | No | Yes (Bedrock + FAISS) | |
| + | | Git remote access | Read-only (clone/pull) | Read/write (push/pull + external sync) | |
| + | | Custom domain | No | Yes (CNAME → {user}.wikibot.io) | |
| + | | Public read-only access | Yes (optional per wiki) | Yes (optional per wiki) | |
| + | | Collaborators per wiki | 3 | 25 | |
| + | | MCP access | Yes | Yes | |
| + | | Web UI | Yes | Yes | |
| + | | Attachment storage | 50MB total | 1GB total | |
| + | | Max attachment size | 5MB | 25MB | |
| + | | Custom wiki styling (CSS) | No | Yes | |
| + | | Create from template repo | No (default template only) | Yes (any Git URL) | |
| + | | REST API access | No | Yes | |
| + | |
| + | ### Pricing |
| + | |
| + | Premium: **$4.99/month**. AWS costs per active premium user are well under $1/month (Bedrock embeddings ~$0.30, EFS/DynamoDB negligible), so margins are healthy. Undercuts Notion Personal Pro ($10/month) by half while offering Git-backed version control and AI-native wiki design that Notion can't match. |
| + | |
| + | ### Enforcement |
| + | |
| + | Tier limits enforced in the Lambda layer before any operation: |
| + | - Wiki creation: check `wiki_count < wiki_limit` |
| + | - Semantic search: check `semantic_search_enabled` on wiki record |
| + | - Page creation: check page count against tier limit |
| + | - ACL grants: check collaborator count against tier limit |
| \ | No newline at end of file |