Home A - Z
Page Index

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 0: Proof of Concept

Goal: Validate the two core technical risks: git on EFS via Lambda, and MCP OAuth via WorkOS.

Two independent tracks that can run with separate managers:

  • Track A: EFS + Lambda (P0-1 → P0-5)
  • Track B: WorkOS + MCP auth (P0-6 → P0-8)

P0-1: Pulumi Scaffold

Parallel group: Track A start Dependencies: None Target: wikibot-io repo, feat/P0-1-pulumi-scaffold

Description: Create the Pulumi project with foundational AWS infrastructure: VPC with 1 public and 1 private subnet (single AZ for dev), security groups, route tables, and gateway endpoints for DynamoDB and S3.

Deliverables:

  • infra/__main__.py with top-level composition
  • infra/components/vpc.py — VPC, subnets, security groups, route tables, gateway endpoints
  • Unit tests verifying resource creation and security group rules
  • pulumi up succeeds against the dev stack

Acceptance criteria:

  • VPC created with correct CIDR, 1 public + 1 private subnet
  • Gateway endpoints for DynamoDB and S3 attached to private subnet route table
  • Security group allows Lambda → EFS (NFS port 2049) and Lambda → internet (egress)
  • All resources tagged with project: wikibot-io, environment: dev
  • Unit tests pass with pulumi.runtime.set_mocks()
  • pulumi up succeeds

P0-2: EFS + Lambda Basic

Parallel group: Track A Dependencies: P0-1 Target: wikibot-io repo, feat/P0-2-efs-lambda

Description: Add EFS filesystem with mount target in the private subnet. Create a Lambda function (Python 3.12, VPC-attached) that mounts EFS and performs basic file read/write. This validates the core infrastructure pattern.

Deliverables:

  • infra/components/efs.py — EFS filesystem, mount target, access point
  • infra/components/lambda_functions.py — Lambda function with VPC config and EFS mount
  • app/poc/efs_test.py — Lambda handler that writes a file, reads it back, returns timing
  • IAM role with EFS and VPC permissions
  • Integration test that invokes the Lambda and verifies file persistence

Acceptance criteria:

  • Lambda can write a file to EFS at /mnt/efs/test.txt
  • Lambda can read the file back and content matches
  • File persists across Lambda invocations (cold and warm)
  • Integration test passes
  • Lambda execution time logged

P0-3: Git on EFS

Parallel group: Track A Dependencies: P0-2 Target: wikibot-io repo, feat/P0-3-git-efs

Description: Lambda function that initializes a bare git repo on EFS, commits a markdown file, reads it back, and lists commits. Validates that git operations work correctly on NFS-mounted storage.

Investigate git library choice: gitpython (shells out to git binary — verify availability in Lambda runtime) vs. dulwich (pure Python, no binary dependency). If git is not available in the Lambda runtime, use dulwich. Document the decision.

Deliverables:

  • app/poc/git_test.py — Lambda handler: init bare repo, commit file, read file, list history
  • Decision documented: gitpython vs. dulwich, with rationale
  • Integration test that exercises the full git lifecycle

Acceptance criteria:

  • Bare git repo created on EFS at a specified path
  • Markdown file committed with author, message, and timestamp
  • File content readable from the repo
  • Commit history retrievable
  • Repo persists across Lambda invocations
  • Concurrent read test: 3 simultaneous Lambda invocations reading the same repo
  • Git library decision documented with rationale

P0-4: X-Ray Tracing

Parallel group: Track A (can run parallel with P0-3) Dependencies: P0-2 Target: wikibot-io repo, feat/P0-4-xray

Description: Enable AWS X-Ray tracing on Lambda and API Gateway. Add custom subsegments for git operations (init, commit, read) so that Phase 0 benchmarks can break down latency by operation.

Deliverables:

  • X-Ray tracing enabled on Lambda function(s) via Pulumi
  • Custom subsegment instrumentation in git test Lambda
  • API Gateway stage with X-Ray enabled (if API Gateway exists at this point; otherwise, just Lambda tracing)

Acceptance criteria:

  • X-Ray traces visible in AWS console after Lambda invocation
  • Custom subsegments for git operations appear in trace timeline
  • Cold start vs. warm start distinguishable in traces

P0-5: Performance Benchmarks

Parallel group: Track A (final) Dependencies: P0-3, P0-4 Target: wikibot-io repo, feat/P0-5-benchmarks

Description: Benchmark script that invokes the git Lambda repeatedly and collects timing data. Measures cold start latency, warm read latency, warm write latency, and concurrent access behavior. Results compared against Phase 0 exit criteria.

Deliverables:

  • scripts/benchmark_efs.py — invokes Lambda N times, collects X-Ray data or Lambda response times
  • Results written to Dev/Phase 0 — EFS Benchmarks wiki note
  • Concurrent write test: 5 simultaneous Lambda invocations writing to the same repo

Acceptance criteria:

  • Warm page read < 500ms (measured over 20+ invocations)
  • Warm page write < 1s (measured over 20+ invocations)
  • Cold start < 5s total (measured over 5+ cold starts)
  • Concurrent reads succeed without errors
  • Concurrent writes succeed (git locking handles serialization)
  • Results documented in wiki

P0-6: WorkOS AuthKit Setup

Parallel group: Track B start (independent of Track A) Dependencies: None Target: wikibot-io repo, feat/P0-6-workos-setup

Description: Set up WorkOS AuthKit with Google OAuth provider. Configure the WorkOS dashboard, obtain API keys, and write a minimal test that authenticates a user and retrieves their profile including raw OAuth provider sub claim.

Deliverables:

  • WorkOS AuthKit configuration (documented, not in code — dashboard setup)
  • app/poc/workos_test.py — script that initiates OAuth flow and prints user profile
  • WorkOS API key stored in Pulumi config (pulumi config set --secret workos_api_key)
  • Documentation of provider sub retrieval (especially Apple, if testable)

Acceptance criteria:

  • Google OAuth login flow completes successfully
  • User profile retrieved with email, name, and raw Google sub claim
  • API key securely stored in Pulumi config
  • Apple provider sub retrieval status documented (verified or flagged as unavailable)

P0-7: FastMCP + WorkOS on Lambda

Parallel group: Track B Dependencies: P0-2, P0-6 Target: wikibot-io repo, feat/P0-7-mcp-workos-lambda

Description: Deploy a minimal FastMCP server on Lambda with WorkOS OAuth 2.1 authentication. The MCP server exposes a single test tool (e.g., echo) that returns its input. Uses Streamable HTTP transport (not SSE). Validates that the FastMCP + WorkOS integration works on Lambda behind API Gateway.

Reference the existing otterwiki-mcp auth implementation for patterns (MultiAuth, InMemoryOAuthProvider, StaticTokenVerifier).

Deliverables:

  • app/poc/mcp_server.py — minimal FastMCP server with WorkOS auth and one test tool
  • Mangum adapter wrapping the MCP server for Lambda
  • API Gateway route for MCP endpoint
  • Unit tests for auth setup (mock WorkOS)
  • Integration test that calls the echo tool with a valid token

Acceptance criteria:

  • MCP server deploys to Lambda successfully
  • API Gateway routes to MCP endpoint
  • OAuth 2.1 flow completes (WorkOS issues token, MCP server validates)
  • Test tool callable with valid auth token
  • Invalid/missing tokens rejected
  • Bearer token auth works alongside OAuth (if MCP_AUTH_TOKEN configured)

P0-8: Claude.ai MCP End-to-End

Parallel group: Track B (final) Dependencies: P0-7 Target: Manual testing (no code deliverable)

Description: Connect Claude.ai to the MCP endpoint deployed in P0-7. Verify that Claude.ai can authenticate via WorkOS OAuth and call the test tool. This is a manual test performed by the human or the manager.

Acceptance criteria:

  • Claude.ai MCP connection configured with the endpoint URL
  • OAuth flow completes in Claude.ai
  • Claude.ai can call the echo tool and receive a response
  • Results documented in wiki

P0-9: Billing Alarm

Parallel group: Can run anytime after P0-1 Dependencies: P0-1 Target: wikibot-io repo, feat/P0-9-billing-alarm

Description: Set up AWS Budgets billing alarm with a $50/month threshold. Email notification to the project owner.

Deliverables:

  • Pulumi resource for AWS Budget with email alert
  • Alert threshold: $50/month

Acceptance criteria:

  • Budget alarm created
  • Email notification configured
  • pulumi up succeeds