Skip to content

README.md

Latest commit

 

History

History
209 lines (161 loc) · 8.19 KB

README.md

File metadata and controls

209 lines (161 loc) · 8.19 KB
Raw

Contributors Forks Stargazers Issues MIT License Azure

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