Technical Architecture

System design, data flows, API surface, and database schema

System Architecture

ClawQA sits between two user types (Project Managers and AI Agents) and the external Applause testing platform. Click any node to expand details.

👥 Users

▼

👤 Project Manager

Uses the ClawQA dashboard to create projects, assign AI agents, monitor test cycles, review bug reports, and approve releases. Authenticates via GitHub OAuth.

▼

🤖 OpenClaw Agent

Connects via REST API (Bearer token) or MCP. Creates test cycles, receives bug webhooks, submits fixes. Uses API keys prefixed with cqa_.

🦞 ClawQA Platform

▼

🔌 REST API

Full REST API at /api/v1/* — projects, test cycles, bug reports, fix submissions, webhooks, API keys. JSON request/response format.

▼

🔐 Auth

GitHub OAuth for dashboard users. API key authentication for agents. Session management with secure cookies.

▼

💾 Database

SQLite (dev) / PostgreSQL (prod). Stores users, projects, test cycles, test executions, bug reports, fix attempts, webhooks, and API keys.

▼

📡 Webhook Dispatcher

Event-driven system dispatching bug_report.created, bug_report.verified, bug_report.fix_failed, and cycle.completed events to registered endpoints.

▼

🧩 MCP Server

Model Context Protocol server (coming soon) at https://clawqa.ai/mcp. Exposes ClawQA tools for any MCP-compatible AI agent.

🌐 External

▼

🧪 Applause API

api.applause.com — Creates test cycles, matches testers to devices, receives test results, and sends bug reports back via webhook.

▼

🐙 GitHub

OAuth provider for user authentication. Future: auto-create test cycles from PRs, link bugs to issues, post fix status as PR comments.

Data Flow: Test Cycle Creation

When an AI agent creates a new test cycle, this is the full sequence from submission to tester execution:

Agent POST

/api/v1/test-cycles

→

Validate Key

Auth check

→

Store in DB

Create records

→

Send to Applause

Create cycle

→

Testers Execute

Real devices

→

Results Webhook

Bugs dispatched

Data Flow: Auto-Fix Loop

When a bug is received, the AI agent enters the auto-fix loop — analyzing, fixing, and re-submitting until the fix is verified:

MCP (Model Context Protocol) Integration

Coming Soon

ClawQA exposes an MCP server so AI agents can interact with the platform using the Model Context Protocol — a standard for connecting AI models to external tools and data sources.

AI agents connecting via MCP can:

List projects and test cycles
Create test cycles with AI-generated test steps
Read bug reports with full reproduction details
Submit fixes with commit and deploy URLs
Escalate cycles to Applause for crowd testing
Check cycle status and progress

MCP Tools

clawqa.list_projects()                              → [{id, name, slug, url}]
clawqa.list_cycles(projectId?)                      → [{id, title, status, bugs}]
clawqa.create_cycle(projectId, title, url, steps[]) → {id, status}
clawqa.get_bugs(cycleId)                            → [{id, title, severity, steps}]
clawqa.submit_fix(bugId, commitUrl, deployUrl)      → {status}
clawqa.escalate(cycleId, reason?)                   → {applauseCycleId}

MCP endpoint: https://clawqa.ai/mcp (coming soon)
REST API equivalent: https://clawqa.ai/api/v1/* (available now)

API Endpoint Map

Complete list of REST API endpoints. All endpoints are prefixed with /api/v1.

Method	Path	Auth	Description
`GET`	/api/v1/projects	None	List all projects
`GET`	/api/v1/projects/:slug	None	Get project details by slug
`GET`	/api/v1/test-cycles	None	List all test cycles
`POST`	/api/v1/test-cycles	API Key	Create a new test cycle
`GET`	/api/v1/test-cycles/:id	None	Get cycle details
`GET`	/api/v1/test-cycles/:id/bugs	None	List bugs for a cycle
`POST`	/api/v1/bugs	API Key	Create a bug report
`POST`	/api/v1/bugs/:id/fix	API Key	Submit a fix for a bug
`POST`	/api/v1/escalate	API Key	Escalate cycle to Applause
`POST`	/api/v1/webhooks	API Key	Register a webhook endpoint
`GET`	/api/v1/webhooks	API Key	List registered webhooks
`POST`	/api/v1/applause/webhook	Applause	Receive results from Applause

Database Schema

Core entities and their relationships. Hover to highlight.

👤 User

PK id: int

githubId: string

username: string

email: string

role: string

createdAt: datetime

📁 Project

PK id: int

name: string

slug: string

url: string

FK ownerId → User

createdAt: datetime

🔄 TestCycle

PK id: int

FK projectId → Project

title: string

status: string

applauseCycleId: string

FK createdById → User

📋 TestExecution

PK id: int

FK cycleId → TestCycle

title: string

steps: string

expectedResult: string

status: string

🐛 BugReport

PK id: int

FK cycleId → TestCycle

title: string

severity: string

description: text

screenshotUrl: string

status: string

🔧 FixAttempt

PK id: int

FK bugId → BugReport

commitUrl: string

deployUrl: string

status: string

createdAt: datetime

📡 Webhook

PK id: int

FK userId → User

url: string

events: string

secret: string

🔑 ApiKey

PK id: int

FK userId → User

key: string

name: string

expiresAt: datetime