Home A - Z
Page Index

An Otter Wiki

Blame

aaafb5 Claude (MCP) 2026-03-20 19:52:22
[mcp] Archive original AWS Platform_Overview before rewrite
1 
---
2
archived_from: Design/Platform_Overview
3
archived_date: 2026-03-20
4
status: historical
5
note: Original wikibot.io AWS serverless architecture. Superseded by VPS deployment (robot.wtf).
6
---
7
8
This page is part of the **wikibot.io PRD** (Product Requirements Document). See also: [[Design/Data_Model]], [[Design/Auth]], [[Design/Implementation_Phases]], [[Design/Operations]].
9
10
---
11
12
# PRD/TRD: Serverless Wiki-as-a-Service Platform
13
14
> **Superseded.** This page describes the AWS serverless architecture for wikibot.io. The project has pivoted to a VPS deployment as robot.wtf with ATProto auth. See [[Design/VPS_Architecture]] for the current plan. This page is preserved as an archive — the application logic (ACL model, middleware, MCP tools) carries forward; the AWS infrastructure design does not.
15
16
## Overview
17
18
A multi-tenant, serverless platform that lets users create and manage private research wikis — each backed by its own Git repo and exposed via its own MCP endpoint. Built on AWS (Lambda + EFS + DynamoDB + API Gateway) with near-zero cost at rest. Based on the Otterwiki + semantic search + MCP stack already built for the Third Gulf War project. Product name: **wikibot.io**.
19
20
The platform is a freemium service:
21
22
- **Free tier**: 1 wiki, 1 author, full read/write/MCP access, semantic search included
23
- **Premium tier**: Multiple wikis (up to 12), multiple authors (up to 25 per wiki), external Git sync
24
25
---
26
27
## Context
28
29
### Why this exists
30
31
Setting up a research wiki with MCP integration currently requires: forking Otterwiki, writing API and semantic search plugins, deploying an MCP server, configuring reverse proxy + TLS + auth, and wiring it all together. This took weeks of work. The resulting system is useful enough that it should be productized — but the per-instance infrastructure cost and setup complexity make it impractical to self-host for casual use.
32
33
A serverless architecture solves both problems: zero cost when idle (no VPS bill for abandoned wikis), and the setup complexity is absorbed by the platform.
34
35
### Key users
36
37
- **Researcher** — creates wikis, writes/reads notes via MCP from Claude.ai or Claude Code, browses via web UI
38
- **Admin** (initially: just us) — manages user accounts, monitors usage, handles billing tier changes
39
40
### Prior art
41
42
The existing single-tenant system (documented in `otterwiki-research-wiki-prd.md`) proves the core workflow. This PRD describes the multi-tenant wrapper around it.
43
44
---
45
46
## Architecture
47
48
AWS Lambda + EFS + DynamoDB + API Gateway + CloudFront. EFS eliminates the git-on-S3 clone/push cycle — git repos live on a persistent NFS filesystem that Lambda mounts directly.
49
50
```
51
┌──────────────────────────────────────────────────────────────────────┐
52
│ Clients │
53
│ │
54
│ Claude.ai ──── MCP (Streamable HTTP) ──────┐ │
55
│ Claude Code ── MCP (Streamable HTTP) ──────┤ │
56
│ Any MCP client ─ MCP (Streamable HTTP) ────┤ │
57
│ Browser ────── HTTPS ──────────────────────┤ │
58
│ Git CLI ────── HTTPS (smart HTTP) ─────────┤ │
59
│ CLI ────────── HTTPS ──────────────────────┤ │
60
└─────────────────────────────────────────────┼────────────────────────┘
61
│
62
┌─────────────────────────────────────────────▼────────────────────────┐
63
│ Edge / Routing │
64
│ │
65
│ {user}.wikibot.io/{wiki}/mcp → Compute (MCP handler) │
66
│ {user}.wikibot.io/{wiki}/api/* → Compute (REST API handler) │
67
│ {user}.wikibot.io/{wiki}/ → Compute (Otterwiki Flask) │
68
│ {user}.wikibot.io/{wiki}.git/* → Compute (Git smart HTTP) │
69
│ wikibot.io/auth/* → Compute (OAuth flows) │
70
│ wikibot.io/admin/* → Compute (management API) │
71
│ wikibot.io/ → Static (SPA) │
72
│ │
73
│ OAuth JWT validation on all routes except /auth/* and public wikis │
74
└─────────────────────────────────────────────┬────────────────────────┘
75
│
76
┌─────────────────────────────────────────────▼────────────────────────┐
77
│ Compute (scale-to-zero) │
78
│ │
79
│ 1. Resolve user + wiki from hostname + path │
80
│ 2. Check ACL in DynamoDB │
81
│ 3. Access git repo on EFS (/mnt/efs/{user}/{wiki}/repo.git) │
82
│ 4. Route to appropriate handler: │
83
│ - MCP: FastMCP Streamable HTTP handler │
84
│ - API: REST endpoints (same as existing otterwiki-api) │
85
│ - Web: Otterwiki Flask app │
86
│ - Git: Smart HTTP protocol (dulwich) │
87
│ 5. On write: persist repo, write reindex record to DynamoDB │
88
└──────────┬──────────────┬────────────────────────────────────────────┘
89
│ │
90
┌─────▼─────┐ ┌─────▼──────┐
91
│ EFS │ │ DynamoDB │
92
│ │ │ │
93
│ Git repos│ │ Users │───── DynamoDB Streams
94
│ FAISS │ │ Wikis │ │
95
│ indexes │ │ ACLs │ ▼
96
└───────────┘ │ Reindex Q │ Embedding Lambda (VPC+EFS)
97
└────────────┘ MiniLM (local, no Bedrock)
98
```
99
100
### Component inventory
101
102
| Component | Purpose | AWS Service |
103
|-----------|---------|-------------|
104
| Routing / TLS | Request routing, cert management | API Gateway + CloudFront + ACM |
105
| Edge security (post-launch) | Rate limiting, bot control, OWASP rules | WAF (on API Gateway + CloudFront) |
106
| Auth | OAuth (Google, GitHub, Microsoft, Apple) | WorkOS AuthKit (recommended) |
107
| Compute | Application logic, scale-to-zero | Lambda (VPC, Mangum adapter) |
108
| Git storage | Bare git repos | EFS (mounted by Lambda) |
109
| Vector indexes | FAISS files | EFS |
110
| Metadata | Users, wikis, ACLs, reindex queue | DynamoDB |
111
| Secrets | API keys, auth provider secrets, Git creds | Env vars (dev), Secrets Manager (prod) |
112
| Embeddings | Semantic search | all-MiniLM-L6-v2 (runs locally on Lambda) |
113
| Frontend | Static SPA | S3 + CloudFront |
114
| Async jobs | Reindex on write | DynamoDB Streams → Lambda |
115
| Scheduled tasks | Git sync, cleanup jobs | EventBridge Scheduler |
116
| Tracing | Request latency, per-service breakdown | X-Ray |
117
118
For a user with one 200-page wiki that's idle: effectively $0/month (a few KB of DynamoDB, a few MB on EFS Infrequent Access at $0.016/GB/month).