HackOps

Hackathon management platform for structured Microsoft Azure learning events
Register · Score · Approve · Leaderboard · Ship

Quick Start » · Docs · Report Bug

---

HackOps manages the complete lifecycle of a MicroHack event — from team registration and hacker onboarding through rubric-driven scoring, coach review, and a live leaderboard. Built on Azure App Service (containerized) + Azure SQL Database with GitHub OAuth authentication.

---

What It Does

Feature	Description
Team & Hacker Management	Self-service onboarding via 4-digit event code; Fisher-Yates team shuffle; manual reassignment
Rubric-Driven Scoring	Markdown-defined rubric drives all forms, validation, and grade computation — nothing hardcoded
Submission Workflow	Form or JSON file upload → staging queue → coach/admin approve/reject → immutable score record
Live Leaderboard	Auto-refresh every 30s; expandable rows; grade badges (A/B/C/D); award badges; SSR for fast first paint
Challenge Gating	Challenge N+1 unlocks only after Challenge N is approved
Role Management	Admin, Coach, Hacker, Anonymous — invite by GitHub username; primary admin protected from demotion
Audit Trail	Every reviewer action logged with reviewedBy, reviewedAt, reviewReason

---

Tech Stack

Layer	Technology
Frontend	Next.js 15 (App Router), Tailwind CSS 4, shadcn/ui
Backend	Next.js Route Handlers, TypeScript, Zod
Database	Azure SQL Database (S2, 50 DTU)
Auth	Azure App Service Easy Auth — GitHub OAuth only
Compute	Azure App Service (Linux, containerized Node 22)
Registry	Azure Container Registry (ACR Standard)
Seeding	Azure Container Instances (ephemeral, VNet-integrated)
IaC	Bicep + Azure Verified Modules (AVM), GitHub Actions
Observability	Application Insights, Log Analytics
Secrets	Azure Key Vault — zero hardcoded values

All database traffic flows over a Private Endpoint — Azure SQL is never exposed to the public internet, with Entra ID-only authentication.

---

Architecture

GitHub OAuth
     │
     ▼
Azure App Service (Linux / Container)
  ├── Next.js SSR + API Route Handlers
  ├── Easy Auth middleware
  ├── ACR image pull via managed identity
  └── VNet Integration
          │
          ▼  (private endpoint — snet-pe)
  Azure SQL Database (S2)
  Entra-only auth, swedencentral
          │
  ACI seed/migration (ephemeral)
    │
     Key Vault  ·  App Insights  ·  Log Analytics

---

Quick Start

Prerequisites: Docker Desktop, VS Code with Dev Containers extension, GitHub Copilot.

git clone https://github.com/jonathan-vella/hack-ops.git
cd hack-ops
code .

1. Press F1 → Dev Containers: Reopen in Container

2. Copy the environment template and configure:

   cp apps/web/.env.example apps/web/.env.local

3. Start the dev server:

   npm run dev

4. Open http://localhost:3000

For local dev, set DEV_USER_ROLE=Admin and DEV_USER_ID=your-github-id in .env.local to bypass Easy Auth (Easy Auth does not work on localhost).

---

Infrastructure Deployment

All infrastructure is managed via Bicep AVM modules. Every resource includes a 6-character deterministic suffix (take(uniqueString(resourceGroup().id), 6)) for guaranteed uniqueness.

# Deploy dev environment
cd infra/bicep/hackops
./deploy.ps1 -Environment dev -Location swedencentral

See infra/bicep/README.md for full deployment instructions and governance discovery requirements.

---

Roles

Role	Capabilities
Admin	Full control — create/launch/archive hackathons, manage roles, override scores, view audit log
Coach	Review and approve/reject submissions, view all teams
Hacker	Submit evidence for own team, view leaderboard
Anonymous	Blocked entirely — login required

---

Azure Constraints

Designed for enterprise Azure landing zones:

• Zero hardcoded values — all config in Key Vault or environment variables
• Private Endpoint only — publicNetworkAccess: 'Disabled' on Azure SQL
• Azure SQL authentication — Entra ID only (azureADOnlyAuthentication: true)
• Managed Identity for all service-to-service authentication
• Azure Policy compliant — governance discovery required before production deployment
• Minimum 4 tags enforced: Environment, ManagedBy, Project, Owner
• Current region: swedencentral

---

Project Structure

apps/
  web/                  # Next.js 15 application
packages/
  shared/               # Shared TypeScript types
infra/
  bicep/hackops/        # Bicep AVM templates
.github/
  agents/               # Copilot agent definitions
  skills/               # Domain knowledge skills
  instructions/         # File-type coding rules
agent-output/           # Generated infrastructure artifacts
docs/                   # Documentation

See AGENTS.md for the agent workflow map and docs/project-overview.md for a full end-to-end explanation of the project.

---

Contributing & License

Contributions are welcome — see CONTRIBUTING.md for guidelines. MIT License — see LICENSE for details.

---

Made with ❤️ by Jonathan Vella