Developer Architecture

Complete technical reference — v1.0.0

API Routes

DB Models

Dashboard Pages

Core Libraries

Tests (58+27)

MCP Tools

System Overview

👤

Browser

GitHub OAuth / Password

→

🌐

Caddy

TLS + Reverse Proxy

→

⚡

Next.js 16

PM2 :3150

→

💾

SQLite

Prisma ORM

↔

🧪

Crowd Testing

Server: Hetzner 135.181.43.68 · Ubuntu · PM2 process manager
Framework: Next.js 16.1.6 (App Router) · React 19 · TypeScript
Auth: NextAuth v5 — GitHub OAuth + Credentials (demo password)
Database: SQLite via Prisma 6.19.2 — 18 models
Repo: github.com/yoniassia/clawqa · Tag: v1.0.0

File Architecture

src/

app/

(auth)/

(dashboard)/ — Protected route group

layout.tsx — Sidebar navigation layout

dashboard/

page.tsx — Main dashboard with project cards test-cycles/page.tsx — List all test cycles test-cycles/[id]/page.tsx — Cycle detail + steps + bugs bugs/page.tsx — All bug reports analytics/page.tsx — Charts, severity, trends test-plans/page.tsx — Reusable test plan templates test-plans/[id]/page.tsx — Plan detail + execute webhooks/page.tsx — Webhook management + delivery logs browse-tests/page.tsx — Testers browse available tests my-tests/page.tsx — Tester's claimed tests my-tests/[id]/page.tsx — Test execution UI my-bugs/page.tsx — Bugs I reported

api-keys/page.tsx — Generate/revoke API keys projects/[slug]/page.tsx — Project detail settings/page.tsx — Crowd Testing config + connection test

api/ — 38 API routes

auth/[...nextauth]/route.ts — NextAuth handlers mcp/route.ts — MCP JSON-RPC server api-keys/route.ts — Key management me/route.ts — Current user info

v1/ — Public REST API

projects/route.ts — GET/POST projects projects/[slug]/route.ts — Project detail projects/[slug]/agents/route.ts — Assign/list agents projects/[slug]/agents/[userId]/route.ts — Remove agent test-cycles/route.ts — GET/POST cycles test-cycles/[id]/route.ts — Cycle detail test-cycles/[id]/bugs/route.ts — Bugs per cycle test-plans/route.ts — GET/POST plans test-plans/[id]/route.ts — Plan detail test-plans/[id]/execute/route.ts — Instantiate plan → cycle bugs/route.ts — GET/POST bugs bugs/[id]/fix/route.ts — Submit fix attempt auto-fix/trigger/route.ts — Start auto-fix job auto-fix/[attemptId]/status/route.ts — Job progress auto-fix/[attemptId]/complete/route.ts — Mark fix done analytics/route.ts — Bug stats & trends webhooks/route.ts — Register/list webhooks webhooks/test/route.ts — Send test ping webhooks/[id]/deliveries/route.ts — Delivery history escalate/route.ts — Send to Testers escalation-rules/route.ts — Priority routing rules github/connect/route.ts — Link repo to project github/webhook/route.ts — Receive PR events github/prs/[prNumber]/status/route.ts — Test status for PR crowd-testing/status/route.ts — Connection check crowd-testing/results/route.ts — Sync test results crowd-testing/webhook/route.ts — Receive Crowd Testing events

developers/page.tsx — Public API docs portal layout.tsx — Root layout page.tsx — Homepage

lib/ — 8 core modules

auth.ts — NextAuth config (GitHub + Credentials) prisma.ts — Prisma client singleton api-auth.ts — API key validation (SHA-256 hash) crowd-testing.ts — Testing SDK (startTestRun, submitResult...) webhook-dispatcher.ts — HMAC-SHA256 signed delivery + retries rate-limit.ts — Sliding window (100 req/min per key) priority-scoring.ts — Bug priority calculation escalation-engine.ts — Rule-based escalation matching

components/

GlassCard.tsx — Glassmorphism card component Sidebar.tsx — Dashboard sidebar nav TopBar.tsx — Top navigation bar

tests/ — 85 tests total

unit/ — 58 tests (Vitest)

api-auth.test.ts — 4 tests: key validation, hashing api-bugs.test.ts — 2 tests: bug CRUD api-projects.test.ts — 3 tests: project data api-test-cycles.test.ts — 5 tests: cycle data, steps JSON crowd-testing-client.test.ts — 10 tests: SDK methods, config escalation-rules.test.ts — 2 tests: rule matching mcp-tools.test.ts — 3 tests: tool definitions phases456.test.ts — 9 tests: auto-fix, webhooks, crowd-testing phases-7-10.test.ts — 8 tests: plans, analytics, agents, github priority-scoring.test.ts — 6 tests: score calculation rate-limit.test.ts — 3 tests: sliding window schema.test.ts — 1 test: Prisma schema validity webhook-dispatcher.test.ts — 2 tests: HMAC signing

e2e/ — 27 tests (Playwright)

homepage.spec.ts — 5 tests: title, nav, projects, docs, CTA docs.spec.ts — 7 tests: all doc pages load + links api.spec.ts — 8 tests: API endpoints return correct data auth.spec.ts — 4 tests: login redirect, protection webhooks.spec.ts — 3 tests: webhook registration

prisma/

schema.prisma — 18 models, 264 lines dev.db — SQLite database

public/docs/ — Static documentation

index.html, overview.html, architecture.html, phases.html, for-agents.html, for-project-managers.html

Database Schema (18 Models)

Hover over any model to see its relationships.

👤 User

id, name, email, role, image, createdAt

→ Account, Session, ApiKey, Project, Webhook, TestExecution, BugReport, TesterProfile

🔑 Account

provider, providerAccountId, access_token, refresh_token

→ User

🎫 Session

sessionToken, expires

→ User

🔐 ApiKey

keyHash (SHA-256), keyPrefix, name, lastUsedAt, revokedAt

→ User

🧑‍💻 TesterProfile

devices[], languages[], country, bio

→ User (1:1)

📁 Project

name, slug, description, targetUrl, repoUrl, githubOwner, githubRepo, autoFixEnabled

→ User (owner), TestCycle[], AgentAssignment[], EscalationRule[]

🔄 TestCycle

title, description, targetUrl, priority, status, stepsJson, deviceReqs, prUrl, prNumber

→ Project, BugReport[], TestExecution[]

▶️ TestExecution

status, startedAt, completedAt, resultsJson

→ TestCycle, User (tester)

🐛 BugReport

title, severity, status, stepsToReproduce, expectedResult, actualResult, deviceInfo, screenshotUrls

→ TestCycle, User (reporter), FixAttempt[]

🔧 FixAttempt

commitUrl, deployUrl, notes, status

→ BugReport

🔔 Webhook

url, events[], secret (HMAC), active

→ User, WebhookDelivery[]

📬 WebhookDelivery

event, payload, statusCode, responseBody, duration, deliveredAt

→ Webhook

🤖 AutoFixJob

status (queued→analyzing→fixing→deploying→retesting→verified/failed), webhookPayload, retryCount

→ BugReport, FixAttempt

📋 TestPlan

title, description, stepsJson, deviceReqs, browserReqs, priority, version

→ Project, User, TestPlanHistory[]

📜 TestPlanHistory

version, stepsJson, changedAt

→ TestPlan

🤝 AgentAssignment

role (owner/contributor/viewer), permissions

→ Project, User

🚨 EscalationRule

condition (JSON), action (notify/escalate/block-release), targetUrl

→ Project

✅ VerificationToken

identifier, token, expires

(standalone)

API Endpoint Map (38 Routes)

Projects & Agents

Method	Path	Auth	Description
GET	`/api/v1/projects`	None	List all projects
POST	`/api/v1/projects`	API Key	Create project
GET	`/api/v1/projects/:slug`	None	Project detail
GET	`/api/v1/projects/:slug/agents`	API Key	List assigned agents
PUT	`/api/v1/projects/:slug/agents`	API Key	Assign agent to project
DEL	`/api/v1/projects/:slug/agents/:userId`	API Key	Remove agent

Test Cycles & Plans

Method	Path	Auth	Description
GET	`/api/v1/test-cycles`	None	List all cycles
POST	`/api/v1/test-cycles`	API Key	Create test cycle
GET	`/api/v1/test-cycles/:id`	None	Cycle detail
GET	`/api/v1/test-cycles/:id/bugs`	None	Bugs for cycle
GET	`/api/v1/test-plans`	None	List test plans
POST	`/api/v1/test-plans`	API Key	Create test plan
GET	`/api/v1/test-plans/:id`	None	Plan detail
POST	`/api/v1/test-plans/:id/execute`	API Key	Create cycle from plan

Bugs & Auto-Fix

Method	Path	Auth	Description
GET	`/api/v1/bugs`	None	List bug reports
POST	`/api/v1/bugs`	API Key	Create bug report
POST	`/api/v1/bugs/:id/fix`	API Key	Submit fix attempt
POST	`/api/v1/auto-fix/trigger`	API Key	Start auto-fix job
GET	`/api/v1/auto-fix/:id/status`	API Key	Job progress
POST	`/api/v1/auto-fix/:id/complete`	API Key	Mark fix deployed

Webhooks & Analytics

Method	Path	Auth	Description
GET	`/api/v1/webhooks`	API Key	List webhooks
POST	`/api/v1/webhooks`	API Key	Register webhook
POST	`/api/v1/webhooks/test`	API Key	Send test ping
GET	`/api/v1/webhooks/:id/deliveries`	API Key	Delivery history
GET	`/api/v1/analytics`	None	Bug stats & trends

Escalation, GitHub & Crowd Testing

Method	Path	Auth	Description
POST	`/api/v1/escalate`	API Key	Escalate cycle to crowd testers
GET	`/api/v1/escalation-rules`	API Key	List escalation rules
POST	`/api/v1/escalation-rules`	API Key	Create rule
POST	`/api/v1/github/connect`	API Key	Link repo to project
POST	`/api/v1/github/webhook`	GitHub	Receive PR events
GET	`/api/v1/github/prs/:num/status`	None	Test status for PR
GET	`/api/v1/crowd-testing/status`	None	Connection check
POST	`/api/v1/crowd-testing/results`	API Key	Sync test results
POST	`/api/v1/crowd-testing/webhook`	Crowd Testing	Receive results

MCP & Internal

Method	Path	Auth	Description
POST	`/api/mcp`	API Key	MCP JSON-RPC — 6 tools: list_projects, list_cycles, create_cycle, get_bugs, submit_fix, escalate
GET	`/api/api-keys`	Session	Manage API keys
GET	`/api/me`	Session	Current user info

Data Flows

1. Test Cycle Lifecycle

🤖

AI Agent

POST /test-cycles

→

📋

Created

Steps stored in DB

→

🚀

Escalate

POST /escalate

→

🧪

Crowd Testing

Humans test

→

🐛

Bugs

Webhook callback

→

🔧

Auto-Fix

AI writes fix

→

✅

Verified

Re-tested & passed

2. Auto-Fix Loop

📩

Bug Webhook

bug_report.created

→

🔍

Analyze

Read bug details

→

✏️

Fix Code

Write & commit

→

🚢

Deploy

Push to staging

→

📤

Submit Fix

POST /bugs/:id/fix

→

🧪

Re-test

Crowd Testing verifies

→

✅❌

Result

Verified or retry

3. MCP Tool Call

🤖

AI Agent

MCP client

→

🔌

Initialize

Get capabilities

→

📜

tools/list

Discover 6 tools

→

⚡

tools/call

Execute tool

→

📦

Result

Structured JSON

Test Coverage

Unit Tests (Vitest)

E2E Tests (Playwright)

Unit Test Files

E2E Spec Files

api-auth.test.ts

4 tests — API key validation, SHA-256 hashing, revoked key rejection

api-bugs.test.ts

2 tests — Bug report CRUD operations

api-projects.test.ts

3 tests — Project listing, slug lookup, data integrity

api-test-cycles.test.ts

5 tests — Cycle count, steps JSON parsing, priority validation

crowd-testing-client.test.ts

10 tests — SDK methods, configured/unconfigured states, status values

escalation-rules.test.ts

2 tests — Rule condition matching, action execution

mcp-tools.test.ts

3 tests — Tool definitions, schemas, protocol compliance

phases456.test.ts

9 tests — Auto-fix jobs, webhook delivery, testing integration

phases-7-10.test.ts

8 tests — Test plans, analytics, agent assignments, GitHub

priority-scoring.test.ts

6 tests — Score calculation, severity weighting

rate-limit.test.ts

3 tests — Sliding window, 429 responses, key isolation

schema.test.ts

1 test — Prisma schema validity, 18 models present

webhook-dispatcher.test.ts

2 tests — HMAC-SHA256 signing, header format

AI vs Human Testing Matrix

What ClawQA's AI can verify automatically vs what must be escalated to crowd testers's human testers.

🤖 AI Can Test (Automated)

API endpoint responses (status codes, JSON shape)
Authentication flows (Playwright headless)
Database CRUD operations
Webhook delivery & HMAC signatures
MCP JSON-RPC protocol compliance
Rate limiting (429 responses)
Priority scoring calculations
Escalation rule matching
Test plan versioning logic
API key generation & revocation
Data validation & error handling
Redirect chains (/docs → /docs/)

👤 Humans Must Test (Crowd Testing)

Real GitHub OAuth on phones (iOS Safari, Android Chrome)
Cross-browser visual rendering (glassmorphism, backdrop-blur)
Touch interactions (mobile nav hamburger, tap targets)
Real device performance (slow phones, tablets, 3G)
Accessibility (VoiceOver, TalkBack, screen readers)
Visual regressions (does it actually look right?)
Animated SVG diagrams across browsers
Copy-to-clipboard in code blocks
Password login UX (error states, loading)
Dashboard layout on small tablets
Telegram bot real-device interaction (Clawdet)
Concurrent multi-user scenarios

Infrastructure

Server:     Hetzner 135.181.43.68 (Ubuntu)
Process:    PM2 → clawqa-nextjs (port 3150)
Proxy:      Caddy → TLS + gzip + reverse proxy
Database:   SQLite → /var/www/clawqa-nextjs/prisma/dev.db
Docs:       Static HTML → /var/www/clawqa-nextjs/public/docs/
Domain:     clawqa.ai (Caddy auto-TLS)
Repo:       github.com/yoniassia/clawqa (v1.0.0)
CI:         Manual (npm test + npx playwright test)
Monitoring: PM2 logs + Caddy access logs