Collective Vision - Architecture Overview

60+

API Endpoints

Database Tables

Admin Pages

MCP Tools

Cron Jobs

Migrations

System Architecture

Key Capabilities

Embeddable Widget

Self-contained JS widget. Drop one <script> tag on any page to collect feedback. Anonymous users via localStorage.

Vanilla JS Auto-Provision

Admin Dashboard

Full React admin with feedback management, analytics charts, implementation plans, tag management, and command palette.

React 19 shadcn/ui TanStack

MCP Server

16 tools for AI agents to query feedback, submit items, manage plans, and search semantically via JSON-RPC 2.0.

8 Query Tools 8 Write Tools

AI Pipeline

Auto-classification, sentiment scoring, urgency detection, duplicate finding via vector search, and theme clustering.

Workers AI Vectorize LiteLLM

Implementation Plans

Full lifecycle from draft to release. Real-time collaborative editing via Durable Objects + WebSocket. GitHub issue sync.

Durable Objects CRDT / Yjs GitHub Sync

Multi-Channel Ingest

Import from Discord, Slack, Reddit. Brand monitoring via FireCrawl. Webhook receivers. Batch CSV/JSON import.

Discord Slack Reddit FireCrawl

GET

POST

PATCH

DELETE

:param (dynamic)

Public Widget & Feedback

GET/healthHealth check

GET/widget.jsEmbeddable widget script

GET/api/v1/:workspace/:board/feedbackList feedback (public)

POST/api/v1/:workspace/:board/feedbackSubmit feedback

POST/api/v1/:workspace/:board/feedback/:id/votesVote on feedback

POST/api/v1/:workspace/:board/feedback/:id/commentsAdd comment

Auth Authentication & OAuth

POST/api/v1/auth/signupRegister account

POST/api/v1/auth/loginLogin

POST/api/v1/auth/verify-email/:tokenVerify email

POST/api/v1/auth/forgot-passwordRequest password reset

POST/api/v1/auth/reset-password/:tokenReset password

POST/api/v1/auth/refresh-tokenRefresh JWT

GET/api/v1/oauth/authorize/:providerOAuth initiation

GET/api/v1/oauth/callback/:providerOAuth callback

Admin Feedback Management

GET/api/v1/admin/workspaces/:ws/feedbackList (filtered/sorted/paged)

GET/api/v1/admin/workspaces/:ws/feedback/:idGet detail

PATCH/api/v1/admin/workspaces/:ws/feedback/:idUpdate status/moderation

POST/api/v1/admin/workspaces/:ws/feedback/bulkBulk update

GET/api/v1/admin/workspaces/:ws/statsDashboard stats

GET/api/v1/admin/workspaces/:ws/feedback/recentRecent activity

Admin Tags

POST/api/v1/admin/workspaces/:ws/tagsCreate tag

GET/api/v1/admin/workspaces/:ws/tagsList tags

PATCH/api/v1/admin/workspaces/:ws/tags/:idUpdate tag

DELETE/api/v1/admin/workspaces/:ws/tags/:idDelete tag

AI Analysis & Processing

POST/api/v1/admin/workspaces/:ws/ai/processTrigger AI processing

GET/api/v1/admin/workspaces/:ws/ai/duplicatesDuplicate suggestions

POST/api/v1/admin/workspaces/:ws/ai/duplicates/:id/mergeMerge duplicates

GET/api/v1/admin/workspaces/:ws/ai/themesTheme clusters

GET/api/v1/admin/workspaces/:ws/ai/usageAI usage stats

Plans Implementation Plans

GET/api/v1/admin/workspaces/:ws/plansList plans

POST/api/v1/admin/workspaces/:ws/plansCreate plan

PATCH/api/v1/admin/workspaces/:ws/plans/:idUpdate plan

POST/api/v1/admin/workspaces/:ws/plans/:id/elevate-to-proposalMove to review

POST/api/v1/admin/workspaces/:ws/plans/:id/confirmConfirm plan

POST/api/v1/admin/workspaces/:ws/plans/:id/checkoutCheckout for dev

POST/api/v1/admin/workspaces/:ws/plans/:id/releaseMark released

POST/api/v1/admin/workspaces/:ws/plans/:id/sync-githubSync to GitHub

Ingest Team, Import, Analytics

GET/api/v1/workspaces/:ws/teamList team members

POST/api/v1/workspaces/:ws/inviteInvite user

POST/api/v1/admin/workspaces/:ws/importImport data

POST/api/v1/admin/workspaces/:ws/sourcesAdd external source

GET/api/v1/admin/workspaces/:ws/analyticsAnalytics data

POST/api/v1/admin/workspaces/:ws/reports/generateGenerate PDF report

MCP Model Context Protocol

GET/mcp/.well-known/mcp.jsonMCP discovery

POST/mcp/messageJSON-RPC handler (16 tools)

Widget User Flow (Anonymous)

1. Script Loads

Widget reads data-workspace and data-board from <script> tag. Falls back to script origin for API base.

2. Identity Resolution

Checks localStorage for cv_uid. If absent, generates anon_<random> and stores it.

3. Auto-Provision

First request auto-creates workspace and board via getOrCreateWorkspaceAndBoard().

4. Load Feed

GET feedback list. Shows approved + visible items with aggregated vote counts via LEFT JOIN.

5. Submit / Vote

POST creates feedback (auto-approved). Votes deduplicated by UNIQUE constraint on (feedback_id, user_id).

Widget Embed Code

Authentication Flow

1. Signup

POST /auth/signup with email + password. Password hashed with bcryptjs. Verification email sent via Resend.

2. Verify Email

Click link in email. POST /auth/verify-email/:token. Token is single-use, 24h expiry.

3. Login

POST /auth/login. Returns JWT access token (bearer). Session tracked in sessions table.

4. Access Dashboard

JWT sent as Authorization: Bearer header. Middleware validates token, resolves user + workspace role.

OAuth Alternative

GET /oauth/authorize/:provider redirects to Google/GitHub. Callback creates oauth_accounts link and issues JWT.

Password Reset

POST /forgot-password sends reset email. POST /reset-password/:token with new password. Token single-use.

API Keys

Programmatic access via cv_ prefixed keys. Scoped to workspace. Stored hashed. Used by MCP clients.

Implementation Plan Lifecycle

Draft

→

Proposal in Review

→

Confirmed

→

Checked Out

→

In Development

→

Staging

→

Released

Collaborative Editing

Plans support real-time collaborative editing via Durable Objects + WebSocket connections. Document state persisted as CRDT (Yjs binary). Cursor tracking and user presence. 5-second debounced persistence to D1.

GitHub Integration

Plans can sync to GitHub issues. Fields: github_issue_number, github_repo, release_url. Bidirectional sync on status changes. Community edit suggestions map to PR-style workflow.

Admin Dashboard Pages

Dashboard

Real-time overview with stats cards, activity feed, analytics charts, and priority queue.

DashboardWidgets ActivityFeed AnalyticsCharts PriorityQueue

Feedback

Sortable/filterable table with bulk actions, detail modals, and moderation controls.

FeedbackTable FeedbackDetail FeedbackFilters BulkActionBar ModerationActions

Plans

Implementation plan management with status workflow and collaborative editing.

StatusEditor SavedViews

Landing Page

Marketing page with hero, features, comparison, pricing, and widget demo.

Hero Features Comparison HowItWorks WidgetDemo Pricing FAQ

Shared UI Components (shadcn/ui)

Button Card Dialog Form Input Select Tabs Toast Accordion Avatar Badge Checkbox DropdownMenu Label Separator Skeleton Table

Backend Modules (src/)

lib/auth/

password.ts, tokens.ts, jwt.ts, oauth.ts, validation.ts

lib/ai/

queue.ts, embeddings.ts, vectors.ts, llm.ts, pipeline.ts, taxonomy.ts, priority-scorer.ts, plan-generator.ts

lib/platforms/

reddit.ts, discord.ts, slack.ts

lib/email/

service.ts, templates.ts (via Resend)

lib/github/

client.ts, sync.ts

mcp/tools/

8 query + 8 write tools. JSON-RPC 2.0 dispatch.

Database Schema (D1 / SQLite)

▶ Core: Tenancy & Feedback 7 tables

Table	Key Columns	Constraints
`workspaces`	id, slug, name	UNIQUE(slug)
`boards`	workspace_id, slug, name, is_public	UNIQUE(workspace_id, slug), FK workspace
`end_users`	workspace_id, external_user_id, email, name	UNIQUE(ws, ext_id), UNIQUE(ws, email)
`feedback_items`	board_id, author_id, title, description, status, moderation_state, source, ai_*	FK board, FK author, IDX(board, hidden, mod, status)
`feedback_votes`	feedback_id, user_id, weight	UNIQUE(feedback_id, user_id)
`feedback_comments`	feedback_id, author_id, body, is_internal	FK feedback, FK author
`feedback_tags` + `feedback_item_tags`	name, color / feedback_id, tag_id	Junction table, FK both sides

▶ Migration 001: Authentication 7 tables

Table	Purpose
`users`	Admin/team accounts (email, password_hash, email_verified)
`sessions`	Active login sessions with token_hash and expiry
`team_memberships`	User-workspace links with roles (owner/admin/member/viewer)
`workspace_invitations`	Pending email-based invites with token_hash
`oauth_accounts`	External provider links (Google, GitHub)
`api_keys`	Programmatic access tokens scoped to workspace
`audit_logs`	Security event tracking (action, resource, IP)

▶ Migration 002: AI Infrastructure 4 tables + columns

Table	Purpose
`duplicate_suggestions`	AI-detected duplicates with similarity_score
`themes`	Feedback cluster groups (auto-generated or manual)
`ai_usage`	Per-workspace daily usage (embeddings, LLM calls, tokens)
`ai_dead_letters`	Failed AI job queue for retry/debugging
+ feedback_items columns: ai_status, ai_type, ai_product_area, sentiment_score, urgency_score, priority_score, ai_summary

▶ Migrations 003-006: MCP, Import, Platforms, Plans 12 tables

Table	Migration	Purpose
`mcp_api_keys`	003	MCP-specific API keys with scopes
`webhooks` + `webhook_deliveries`	003	Event subscriptions and delivery audit
`import_jobs` + `import_job_items`	004	Batch import tracking
`external_sources`	004	Connected platform configurations
`brand_mentions` + `brand_keywords`	004	Brand monitoring data
`platform_installations`	005	OAuth tokens for platforms
`implementation_plans`	006	Full lifecycle plans with GitHub sync
`plan_revisions`	006	Version history with diffs
`plan_comments`	006	Threaded discussion on plans
`plan_edit_suggestions`	006	Community-proposed edits

State Management (Frontend)

React Query (TanStack)

All API data fetching uses React Query for automatic caching, background refetching, and mutation invalidation. 30s refetch intervals on dashboard.

WorkspaceContext

React Context stores selected workspace + board in localStorage. All API calls scoped to active workspace. Persists across sessions.

Runtime & Infrastructure

Layer	Technology	Version	Purpose
Runtime	`Cloudflare Workers`	-	Serverless edge compute
Database	`Cloudflare D1`	-	SQLite at edge (26 tables)
AI	`Workers AI`	-	Embeddings + inference
Search	`Cloudflare Vectorize`	-	Semantic vector search
Queues	`Cloudflare Queues`	-	Async AI job processing
Real-time	`Durable Objects`	-	WebSocket + state persistence
Deploy	`Wrangler CLI`	3.99+	Build & deploy pipeline
LLM	`LiteLLM`	-	LLM gateway proxy

Backend Dependencies

Package	Version	Purpose
`typescript`	5.7+	Type safety (ES2022 target, strict)
`zod`	3.24+	Request validation schemas
`bcryptjs`	3.0+	Password hashing
`pdf-lib`	1.17+	PDF report generation
`vitest`	3.2+	Test framework
`@cloudflare/vitest-pool-workers`	0.11+	Workers test environment
`miniflare`	4.x	Local D1/Workers simulation

Frontend Dependencies (admin/)

Package	Version	Purpose
`react`	19	UI framework
`react-router`	7	Client-side routing
`@tanstack/react-query`	latest	Data fetching & caching
`@tanstack/react-table`	latest	Table component
`tailwindcss`	latest	Utility-first CSS
`@radix-ui/*`	latest	Accessible primitives (shadcn/ui)
`react-hook-form`	latest	Form management
`recharts`	latest	Data visualization
`lucide-react`	latest	Icon library
`date-fns`	latest	Date formatting
`vite`	latest	Build tool + HMR

Environment Configuration

DEV

Development

Local D1 with --local --persist
ALLOWED_ORIGINS: *
Hot reload via wrangler dev
Mocked AI bindings

STAGING

Staging

Separate D1 database
ALLOWED_ORIGINS: staging domain
Real AI bindings
npm run deploy:staging

PRODUCTION

Production

Production D1 database
ALLOWED_ORIGINS: production domains
All secrets configured
npm run deploy:production

Scheduled Jobs (Cron)

Schedule	Job	Description
`0 * * * *`	AI Processing	Process pending feedback through AI pipeline
`0 /6 * *`	Brand Monitor	Crawl web for brand mentions via FireCrawl
`0 9 * * *`	Daily Reports	Generate daily summary reports
`0 9 * * 1`	Weekly Reports	Generate weekly trend reports
`0 3 * * *`	Cleanup	Purge expired tokens, stale sessions

CI/CD

SonarQube CI/CD

Dual-project setup (prod + dev). GitHub Actions workflow on push/PR to main. Self-hosted runner with [self-hosted, sonarqube] labels. Secrets: SONAR_TOKEN, SONAR_HOST_URL auto-configured.

Automated Releases

release-please for conventional commit-based releases. GitHub Actions on push to main: opens a Release PR (auto-bump + CHANGELOG); merging it tags the release. Current version: v0.1.0.

Required Secrets

ADMIN_API_TOKEN CLAUDE_API_KEY RESEND_API_KEY GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET LITELLM_API_KEY FIRECRAWL_API_KEY DISCORD_BOT_TOKEN SLACK_CLIENT_SECRET REDDIT_CLIENT_SECRET

Git Workflow

feature/*

→ PR →

dev

→ PR →

main

→

v0.x.x tag

Standard tier: main + dev branches. Conventional commits enforce version bumps. Release PR via release-please on push to main. SonarQube gates on PR.