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 3: Frontend

Goal: SPA for user dashboard, wiki settings, and MCP connection instructions.

P3-1: SPA Scaffold

Parallel group: Phase 3 start Dependencies: None (can start anytime — just needs API from P2-4) Target: wikibot-io repo, feat/P3-1-spa-scaffold

Description: Scaffold the frontend application. Choose framework (React or Svelte — manager decides based on ecosystem maturity and team capabilities). Set up build pipeline with Vite, TypeScript, and basic routing.

Deliverables:

  • app/frontend/ — scaffolded SPA with routing
  • Build pipeline (Vite + TypeScript)
  • Framework decision documented
  • Basic layout: header, sidebar, content area
  • Dev server that proxies API requests to the backend

Acceptance criteria:

  • npm run dev starts local dev server
  • npm run build produces production bundle
  • TypeScript compiles without errors
  • Basic routing works (dashboard, login, settings pages as empty shells)
  • Framework decision documented with rationale

P3-2: Auth Flow

Parallel group: Phase 3 Dependencies: P3-1, P2-2 Target: wikibot-io repo, feat/P3-2-auth-flow

Description: Frontend authentication: login page with OAuth provider buttons, callback handling, JWT storage, authenticated API requests, logout.

Deliverables:

  • Login page with Google (and other configured) OAuth buttons
  • OAuth callback handler (receives auth code, exchanges for platform JWT)
  • JWT stored in httpOnly cookie or localStorage (decide and document tradeoffs)
  • API client module that attaches JWT to requests
  • Protected route wrapper (redirects to login if no valid JWT)

Acceptance criteria:

  • Login redirects to WorkOS AuthKit
  • Callback exchanges code for JWT
  • Authenticated API requests succeed
  • Unauthenticated access redirects to login
  • Logout clears JWT
  • Token refresh works (if implemented)

P3-3: Dashboard

Parallel group: Phase 3 Dependencies: P3-1, P2-4 Target: wikibot-io repo, feat/P3-3-dashboard

Description: User dashboard: list of wikis with metadata, create new wiki button and form.

Deliverables:

  • Dashboard page: wiki list (name, page count, last accessed)
  • Create wiki form (slug, display name, optional description)
  • Empty state for new users
  • Loading and error states

Acceptance criteria:

  • Dashboard shows user's wikis
  • Create wiki form validates slug (URL-safe characters, 3-30 chars)
  • After creation, displays MCP token and connection instructions
  • Wiki list links to wiki web UI and settings page

P3-4: Wiki Settings

Parallel group: Phase 3 Dependencies: P3-3 Target: wikibot-io repo, feat/P3-4-wiki-settings

Description: Wiki settings page: rename wiki, regenerate MCP token, manage collaborators (invite by email, set role, revoke), delete wiki.

Deliverables:

  • Settings page with tabbed sections (general, collaborators, danger zone)
  • Collaborator management: invite form, list with role badges, revoke buttons
  • Token regeneration with confirmation and one-time display
  • Delete wiki with typed-slug confirmation

Acceptance criteria:

  • Can rename wiki display name
  • Can regenerate MCP token (shown once, confirmation required)
  • Can invite collaborator by email with role selection
  • Can change collaborator role
  • Can revoke collaborator access
  • Can delete wiki (requires typing slug to confirm)

P3-5: MCP Connection Instructions

Parallel group: Phase 3 Dependencies: P3-3 Target: wikibot-io repo, feat/P3-5-mcp-instructions

Description: Page showing how to connect MCP clients to the wiki. Copy-paste claude mcp add command with the user's token. Instructions for both Claude.ai (OAuth — just add the URL) and Claude Code (bearer token).

Deliverables:

  • MCP connection page (accessible from dashboard and wiki settings)
  • Copy-to-clipboard for claude mcp add command
  • Instructions for Claude.ai (OAuth flow — add URL)
  • Instructions for Claude Code (bearer token)

Acceptance criteria:

  • claude mcp add command is correct and copyable
  • Claude.ai instructions show the correct MCP endpoint URL
  • Token is displayed (from creation) or "regenerate to see" if not first visit

P3-6: Public Wiki Toggle

Parallel group: Phase 3 Dependencies: P3-4, P2-3 Target: wikibot-io repo, feat/P3-6-public-toggle

Description: Toggle in wiki settings to make a wiki publicly readable. When enabled, unauthenticated users can view (but not edit) the wiki via the web UI.

Deliverables:

  • Toggle switch in wiki settings
  • API call to update wiki is_public flag
  • Frontend handles public wiki URLs (no auth redirect)

Acceptance criteria:

  • Toggle updates DynamoDB is_public flag
  • Public wiki viewable without login
  • Public wiki not editable without login
  • Private wiki still requires auth

P3-7: Static Hosting

Parallel group: Phase 3 (parallel with P3-1 — infrastructure can be set up early) Dependencies: P3-1 (needs build output) Target: wikibot-io repo, feat/P3-7-static-hosting

Description: S3 bucket + CloudFront distribution for serving the SPA. Pulumi resources.

Deliverables:

  • infra/components/frontend.py — S3 bucket, CloudFront distribution, OAI
  • Build and deploy script (upload to S3, invalidate CloudFront)
  • Custom domain: wikibot.io (root domain serves SPA)

Acceptance criteria:

  • SPA accessible at https://wikibot.io/
  • CloudFront serves with correct cache headers
  • SPA routing works (all paths serve index.html, client-side routing handles them)
  • Build artifacts uploaded to S3

P3-8: Phase 3 E2E Test

Parallel group: Phase 3 (final) Dependencies: All P3 tasks Target: wikibot-io repo, feat/P3-8-e2e

Description: End-to-end user journey: signup → create wiki → connect MCP → use wiki → manage collaborators.

Deliverables:

  • tests/e2e/test_phase3.py
  • Results documented in wiki

Acceptance criteria:

  • New user signs up via OAuth → lands on dashboard
  • Creates wiki → sees MCP token and instructions
  • Connects Claude.ai via MCP OAuth → can read/write notes
  • Connects Claude Code via bearer token → can read/write notes
  • Invites collaborator → collaborator can access wiki
  • Public wiki toggle → anonymous read access works