Readme
Hackorda is two products in one repo:
- Quiz Learning Platform — the original LMS with quizzes, courses, leaderboard
- Test Cycles vertical — a QA management system layered on top (added 2026-Q2)
📚 Documentation Structure
🧭 Read this first
- System Overview & Scaling Guide — the front-door: what Hackorda is, the tech stack, how it's all wired (runtime + code + deploy), the permission model (in-app RBAC + repo/ops governance), and the layer-by-layer scaling roadmap. Links out to everything below.
📋 Roadmaps
- Infra Roadmap — Neon → queue → scale → multi-tenant
- Core Feature Roadmap — product buckets A–I, Now/Next/Later
- Agent Platform Strategy — MCP surface, agentic QA, compute map, business model
🔐 Reference
- Permissions & Access Levels — full role/scope/key model including agents
- Authentication — Clerk implementation
📖 Guides (how-tos)
- Agent Quickstart — file your first bug via MCP in 5 min
- CI Integration — auto-file bugs from failed tests
🗂 Use cases
- Triage Automation — UC-1: agent pre-triages low-severity issues
- Autonomous Regression — UC-5: Hackorda runs the tests (Phase 2)
🔄 Test Cycles (QA vertical) — start here for what's shipped
- Test Cycles — canonical reference: cycle docs, inline media, run packs, AI agents, role model, API surface
- Feature Matrix — every feature: shipped/planned/deferred registry
- Flows — 16 canonical user journeys (F-01→F-16) with acceptance criteria
- Deployment — droplet ops, GHCR, AI key setup
- QA onboarding handbook — auto-seeded into the Hackorda Onboarding cycle
- QA test cases — auto-seeded into the cycle as a runbook doc
Legacy quiz platform
- Tech Stack - Technologies, dependencies, and architecture
- Features - Quiz / course features (does NOT cover Test Cycles)
- Database Schema - Quiz schema (does NOT cover Test Cycles tables — see test-cycles.md)
- Agent API & platform - Programmatic API, keys, and scopes (interactive reference under
build/api-reference) - Authentication - Auth system and role management
- Development Guide - Setup and development workflows
🚀 Quick Start
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env.local
# Run database migrations
npm run migrate
# Seed database (optional)
npm run seed
# Start development server
npm run dev🎯 Key Features
Quiz platform:
- Multi-role quiz system — random quizzes and timed exams
- Admin dashboard — course and user management
- Module-based permission system
- Real-time leaderboard
- Course management
Test Cycles vertical (see test-cycles.md):
- Notion-style cycle documents with inline screenshots / videos
- Issue intake with AI-suggested title / severity / bug type
- Run packs — drop session recordings onto a test run
- Auto-generated session recap on End Run
- Auto-generated stakeholder report on cycle close
- Issue payout state machine (Kaspi / bank / cash)
- Tester role assignment from Profile → Actions
- Graceful AI failure UX (out-of-credits / rate-limit / auth)
🛠️ Tech Highlights
- Next.js 15 with App Router
- Clerk Authentication with role-based access
- Drizzle ORM with PostgreSQL
- TanStack Query for state management
- TailwindCSS 4 (alpha) for styling
- TypeScript for type safety
📊 Current Status
The platform is feature-complete with a few schema inconsistencies and type safety improvements needed.
🤝 Contributing
- Check the Development Guide
- Follow TypeScript and database naming conventions
- Add tests for new features
- Update documentation as needed