Home A - Z
Page Index

This page is part of the wikibot.io PRD (Product Requirements Document). See also: Design/Platform_Overview, Design/Data_Model, Design/Auth, Design/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, author count per wiki)
  3. Upgrade/downgrade flows in frontend
  4. Webhook handling for subscription lifecycle
  1. ReindexQueue DynamoDB table with Streams enabled
  2. Embedding Lambda (VPC+EFS, container image with all-MiniLM-L6-v2)
  3. DynamoDB Streams → Lambda event source mapping
  4. DynamoDB write on page save in wiki Lambda
  5. FAISS index build on EFS (384-dim MiniLM vectors)
  6. Wire into MCP and API handlers
  7. Available to all users (not tier-gated)

See Design/Async_Embedding_Pipeline for full architecture.

Phase 7: Deferred features (build when there's demand)

Not scheduled. Build these when users ask for them, not before.

  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

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 and semantic search.

MCP endpoint (existing, adapted)

Same tools as the existing otterwiki-mcp, exposed at /{user}/{wiki}/mcp. Authentication via bearer token or OAuth.

Freemium Tiers

The premium tier is about scale, not features. Free users get a complete, fully-featured wiki. Premium unlocks multiple wikis and collaboration.

Feature Free Premium
Wikis 1 12
Authors per wiki 1 25
Pages per wiki 500 Unlimited
Full-text search Yes Yes
Semantic search Yes (MiniLM + FAISS) Yes
Git remote access Read-only (clone/pull) Read-only (clone/pull)
Public read-only access Yes (optional per wiki) Yes (optional per wiki)
MCP access Yes Yes
Web UI Yes Yes
REST API access Yes Yes
Attachment storage 50MB total 1GB total
Max attachment size 5MB 25MB

Deferred features (build when there's demand)

These were originally planned as premium differentiators but don't fit the "scale, not features" model. Defer until users ask for them:

  • Read/write Git remote access (push/pull)
  • External Git sync (bidirectional, GitHub/GitLab)
  • Custom domains (CNAME + TLS provisioning)
  • Custom wiki styling (CSS)
  • Create wiki from template repo

Pricing (undecided — two options)

AWS costs per user are near-zero regardless of usage. Margins are essentially 100% minus Stripe's cut under either model. The pricing decision is about conversion, simplicity, and what signal we want to send — not about covering costs.

Option A: Flat tier — $4.99/month

One price, one upgrade. Free users get 1 wiki and 1 author. Paying users get 12 wikis and 25 authors per wiki. Annual option: $49/year (~2 months free).

Pros: simple Stripe integration (one subscription plan), higher ARPU per paying user, Stripe's per-transaction fee (\(0.30 + 2.9%) is a smaller percentage of the charge. Comparable to Obsidian Sync (\)5/month) and well under Notion Plus ($10/user/month).

Cons: the jump from $0 to $5 is a real psychological barrier. Users who only want a second wiki are paying for 12 wikis and 25 collaborators they don't need. "Premium tier" language and comparison tables add friction.

Option B: Per-wiki — $1/month per additional wiki

No tiers. One free wiki per account. Every additional wiki costs $1/month. Collaborators are unlimited (or generous — e.g., 25 per wiki for everyone). Bill monthly in aggregate.

Pros: the upgrade decision is tiny ("add a wiki for a dollar"). No tier concept, no feature gating, no comparison tables. The pitch fits on a button: "One wiki free. Extra wikis, a dollar a month each." Conversion rate from free to paid should be higher because the barrier is lower. Pricing scales linearly with value received.

Cons: lower ARPU — a typical researcher with 2–3 projects pays $2–3/month instead of $5. Stripe's per-transaction fee hurts more on small charges (on a $2 charge, Stripe takes ~18%; on $5, it's ~9%). Slightly more billing complexity (metered/usage-based Stripe integration vs. simple subscription). Revenue from a 25-person team using one wiki: $0.

Competitive context (March 2026):

The market doesn't have a direct comparable — no one offers a hosted, git-backed, MCP-native research wiki as a service. The closest reference points are adjacent products: Obsidian (free local app, $5/month sync, $10/month publish, \(50/year commercial), Notion (\)10/user/month for teams), Roam Research ($15/month), and self-hosted options like Docmost (free, but you run it yourself). Wikibot.io's differentiator is zero-setup MCP integration with semantic search — a combination none of these offer.

Decision needed before Phase 5. Either model works with the current architecture. The data model supports both (wiki count is already tracked). Phase 5 implementation differs slightly: Option A is a simple Stripe subscription; Option B is usage-based billing with monthly aggregation.

Enforcement

Tier limits enforced in the Lambda layer before any operation:

  • Wiki creation: check wiki_count < wiki_limit
  • Page creation: check page count against tier limit
  • ACL grants: check collaborator count against tier limit (1 for free, 25 for premium)