Home A - Z
Page Index
Properties 
## How to read this document

- Dependencies list task IDs that must be complete before this task starts
- Parallel group identifies tasks that can run simultaneously within a phase
- Target identifies which repo and branch the work goes into
- Tasks are numbered P{phase}-{sequence} (e.g., P0-3)
- Acceptance criteria are binary — pass or fail, no judgment calls

Phase 1: Single-User Serverless Wiki

Goal: Port the existing Otterwiki + API + semantic search + MCP stack to run on Lambda + EFS. Single user, single wiki, no multi-tenancy.

Status: COMPLETE. All tasks done, gate passed 2026-03-13. See Dev/Phase_1_Gate_Results for full validation results.

P1-1: Mangum Adapter for Otterwiki

Parallel group: Can start during Phase 0 (upstream work) Dependencies: None (upstream contribution, independent of wikibot-io infra) Target: otterwiki fork, PR to main Status: COMPLETE

Description: Add Lambda compatibility to Otterwiki via the Mangum adapter. Mangum wraps Flask/WSGI apps for Lambda invocation. The adapter should be opt-in — Otterwiki continues to work as a normal Flask app when not on Lambda.

Investigate Otterwiki's filesystem assumptions beyond the git repo: config files, static assets, session storage, temporary files. Document what needs to live on EFS vs. what can be ephemeral.

Note: Ended up using apig-wsgi (not Mangum) because Mangum is ASGI-only since v0.15+ and Otterwiki is a WSGI/Flask app. Custom lambda_init.py handler in wikibot-io/app/otterwiki/.

Deliverables:

  • wikibot-io/app/otterwiki/lambda_init.py — apig-wsgi handler with WSGI middleware for non-ASCII PATH_INFO
  • Documentation of filesystem assumptions and EFS requirements
  • No changes to existing Otterwiki behavior

Acceptance criteria:

  • Otterwiki can be invoked via Lambda handler (apig-wsgi, not Mangum)
  • Existing test suite still passes
  • Static assets served correctly
  • Config file loading works from EFS path
  • Git repo operations work with EFS-mounted repo path
  • No import errors when running outside Lambda

Parallel group: Can start during Phase 0 (upstream work) Dependencies: None (upstream contribution, independent of wikibot-io infra) Target: otterwiki-semantic-search repo, PR to main Status: COMPLETE

Description: Add FAISS as an alternative vector store backend alongside the existing ChromaDB backend. FAISS stores indexes as files on disk (suitable for EFS). The backend is selected via configuration.

The embedding function must be pluggable: the existing all-MiniLM-L6-v2 sentence-transformer for local/ChromaDB use, and a Bedrock titan-embed-text-v2 adapter for Lambda use. The Bedrock adapter is a new addition but should be a clean interface implementation, not Lambda-specific.

Reference the PRD's FAISS details: IndexFlatIP, sidecar metadata in embeddings.json, search deduplication by page.

Deliverables:

  • otterwiki_semantic_search/backends/faiss_backend.py — FAISS index management (create, upsert, delete, search)
  • otterwiki_semantic_search/backends/chroma_backend.py — extracted from existing code
  • otterwiki_semantic_search/backends/base.py — abstract backend interface
  • otterwiki_semantic_search/embeddings/bedrock.py — Bedrock titan-embed-text-v2 adapter
  • otterwiki_semantic_search/embeddings/base.py — abstract embedding interface
  • Configuration switch: VECTOR_BACKEND=faiss|chroma, EMBEDDING_MODEL=local|bedrock
  • Unit tests for FAISS backend (using /tmp for index files)
  • Unit tests for Bedrock embedding adapter (mocked)
  • Existing ChromaDB tests still pass

Acceptance criteria:

  • FAISS backend stores/retrieves/deletes vectors correctly
  • Sidecar metadata (embeddings.json) maps index positions to page paths and chunk text
  • Search deduplicates by page, returns top N unique pages
  • Bedrock adapter produces vectors of correct dimensionality
  • Backend is selected by config, defaults to ChromaDB for backward compatibility
  • Existing tests pass without modification
  • New tests cover FAISS CRUD and search operations

P1-3: Otterwiki on Lambda

Parallel group: Phase 1 core Dependencies: P0-2 (EFS + Lambda infra), P1-1 (Mangum adapter) Target: wikibot-io repo, feat/P1-3-otterwiki-lambda Status: COMPLETE

Description: Deploy Otterwiki to Lambda using the apig-wsgi adapter from P1-1. Configure it to use a git repo on EFS. Verify the web UI works end-to-end: browse pages, create pages, edit pages, view history.

Deliverables:

  • Pulumi Lambda function for Otterwiki with EFS mount
  • Otterwiki configuration for Lambda environment (EFS paths, settings)
  • API Gateway route for web UI (/{path+})
  • Integration test: create page via web UI API, read it back

Acceptance criteria:

  • Otterwiki web UI loads in a browser
  • Can create, edit, and delete pages
  • Page history works
  • Static assets (CSS, JS) load correctly
  • Git repo on EFS persists across invocations

P1-4: REST API on Lambda

Parallel group: Phase 1 (parallel with P1-5, P1-6 once P1-3 lands) Dependencies: P1-3 Target: wikibot-io repo, feat/P1-4-api-lambda Status: COMPLETE

Description: Deploy the existing otterwiki-api plugin on Lambda alongside Otterwiki. Verify all API endpoints work. The API plugin is already a Flask blueprint — it should load naturally in the Lambda environment.

Deliverables:

  • API plugin installed and loaded in Lambda Otterwiki instance
  • API Gateway routes for /api/v1/*
  • Integration tests: CRUD pages via API, search, link graph, changelog

Acceptance criteria:

  • All existing API endpoints respond correctly
  • API key auth works via env var
  • WikiLink index builds on startup
  • Full-text search returns results
  • Page create/read/update/delete cycle works
  • Link graph queries return correct data

Note: Minor issue found during gate: GET /pages/{path}/links returns 404 due to Flask route priority. The MCP get_links tool works via a different URL pattern. Low priority fix.

P1-5: MCP Server on Lambda

Parallel group: Phase 1 (parallel with P1-4, P1-6) Dependencies: P1-3, P0-7 (MCP + WorkOS on Lambda) Target: wikibot-io repo, feat/P1-5-mcp-lambda Status: COMPLETE

Description: Deploy the existing otterwiki-mcp server on Lambda. Adapt from SSE to Streamable HTTP transport. The MCP server calls the REST API (P1-4) internally. Auth via WorkOS OAuth (from P0-7).

Decision: Separate Lambdas. Otterwiki needs VPC + EFS; MCP is stateless HTTP proxy. Coupling them would add VPC complexity to MCP for no benefit.

Deliverables:

  • MCP server deployed on separate Lambda (stateless, no VPC)
  • Streamable HTTP transport via json_response=True (API Gateway doesn't support SSE)
  • All 12 MCP tools functional
  • Integration test: read_note, write_note, search_notes via MCP protocol

Acceptance criteria:

  • All MCP tools return correct results
  • OAuth authentication works (WorkOS AuthKit, fixed in P1-9)
  • Bearer token authentication works
  • Streamable HTTP transport functions correctly
  • Architecture decision (same vs. separate Lambda) documented with rationale

P1-6: Semantic Search on Lambda

Parallel group: Phase 1 (parallel with P1-4, P1-5) Dependencies: P1-3, P1-2 (FAISS backend) Target: wikibot-io repo, feat/P1-6-semantic-search-lambda Status: COMPLETE

Description: Deploy the semantic search plugin on Lambda using the FAISS backend from P1-2. FAISS index stored on EFS alongside the git repo. Embedding via Bedrock titan-embed-text-v2 (requires a VPC interface endpoint for Bedrock — add to Pulumi if not already present).

Deliverables:

  • Semantic search plugin deployed with FAISS backend
  • Bedrock VPC endpoint added to Pulumi
  • FAISS index persists on EFS
  • FAISS stripped to AVX2-only to fit 250MB Lambda package limit (163MB total)

Acceptance criteria:

  • Semantic search endpoint returns relevant results
  • FAISS index persists across Lambda invocations
  • Reindex endpoint works (full rebuild from repo)
  • Bedrock embedding calls succeed from VPC Lambda

P1-7: Routing and TLS

Parallel group: Phase 1 Dependencies: P1-3 Target: wikibot-io repo, feat/P1-7-routing-tls Status: COMPLETE

Description: Configure API Gateway routing for all endpoints: web UI, REST API, MCP. Set up a custom domain with TLS via ACM. Route 53 DNS record pointing to API Gateway.

Deliverables:

  • infra/components/api_gateway.py — routes for web UI, API, MCP
  • infra/components/dns.py — Route 53 record + ACM certificate
  • Pulumi outputs for endpoint URLs

Acceptance criteria:

  • https://dev.wikibot.io/ serves Otterwiki web UI
  • https://dev.wikibot.io/api/v1/health returns 200
  • https://dev.wikibot.io/mcp accepts MCP connections
  • TLS certificate valid and auto-renewing (ACM) — TLSv1.3, Amazon RSA 2048, expires 2026-09-26
  • All routes pass through to correct Lambda handlers

P1-8: Phase 1 E2E Test

Parallel group: Phase 1 (final — all other P1 tasks must complete) Dependencies: P1-4, P1-5, P1-6, P1-7 Target: wikibot-io repo, feat/P1-8-e2e Status: COMPLETE

Description: End-to-end test covering the full single-user workflow: browser creates a page, API reads it, MCP reads it, semantic search finds it.

Deliverables:

Acceptance criteria:

  • Create page via Otterwiki web UI → readable via API and MCP
  • Create page via API → visible in web UI and searchable
  • Write via MCP → visible in web UI and API
  • Semantic search finds pages by meaning, not just keywords
  • Git history shows correct authorship for all write paths

P1-9: Self Hosting

Dependencies: P1-8 Target: wikibot-io repo (config), dev wiki repo (content) Status: COMPLETE

Description: Migrate the local development wiki from docker-compose to dev.wikibot.io. Use Otterwiki's built-in Git HTTP server (GIT_WEB_SERVER=True) to git push the dev wiki repo directly, preserving full git history.

Platform config already set: RETAIN_PAGE_NAME_CASE=True, TREAT_UNDERSCORE_AS_SPACE_FOR_TITLES=True, GIT_WEB_SERVER=True.

Additional work done during P1-9:

  • Fixed WSGI PATH_INFO encoding for non-ASCII characters (em dashes, etc.)
  • Implemented space→underscore filename normalization (otterwiki fork feat/space-underscore-normalization)
  • Added resolve_filename migration fallback in otterwiki-api
  • Renamed all 30 wiki pages to use underscores
  • Fixed MCP OAuth discovery routing (P1-9 addendum, see Tasks/P1-9_MCP_OAuth_Routing)

Deliverables:

  • dev.wikibot.io hosts the complete dev wiki with full git history
  • Claude Code MCP config updated to use remote server
  • Local docker-compose dev wiki shut down

Acceptance Criteria:

  • git push succeeds with full history preserved
  • User spot checks https://dev.wikibot.io/ to confirm content looks correct
  • Agent spot checks via remote MCP to confirm content matches local
  • Semantic search returns results on remote instance (233 chunks, 30 pages)
  • Agent can read/write wiki pages via remote MCP to continue Phase 2 work