Project Write-Up: DOGFOOD

Competition / Hackathon Quest Submission

Project Name: DOGFOOD — Autonomous Hackathon Evaluation & Scoring Platform

Tagline: "Build the platform that will judge you."

Tiers Claimed & Verified: T1 Core, T2 Judging, T3 Public Features, T4 Stretch Architecture

Live Appliance URL: http://localhost:8080 (Single-Port Offline Appliance)

GitHub Repository: https://github.com/Naman-mahi/dogfoodhackathon

1. Executive Summary & Inspiration

Every year, hackathons around the globe suffer from the exact same structural failures:

• Anchoring Bias & Judge Collusion: Evaluators look at other judges' scores or discuss entries prematurely, inflating popular teams and penalizing unconventional architectures.
• Evaluator Variance (Harshness vs. Leniency): A project evaluated by three rigorous judges giving 7.5s loses to an average project evaluated by two lenient judges giving 9.5s.
• Review Starvation: Some submissions receive five thorough reviews while neighboring projects receive only one or two due to uncoordinated queueing.
• Catastrophic Offline Failures: Venue Wi-Fi crashes, cloud OAuth providers fail, or remote database timeouts break in-person judging.

DOGFOOD was built to solve these systemic problems once and for all. It is an autonomous, zero-trust, single-port offline appliance running on port 8080 that combines cryptographic peer-isolated blind judging, mathematical Empirical Bayes score calibration, and real-time organizer queue orchestration into a modern, production-grade light-themed web portal.

2. What DOGFOOD Does

DOGFOOD provides a unified, end-to-end hackathon operating system across four dedicated roles:

2.1 For Judges (/dashboard/judge)

• Blind Evaluation Queue: Judges only see projects assigned to their designated tracks.
• Cryptographic Peer Isolation Barrier: Backend-enforced isolation ensures evaluators cannot inspect peer scores, comments, or competitor leaderboards until the organizer officially closes the evaluation window.
• Multi-Dimensional Rubric Grading: Fine-grained sliders for Functionality (40%), Technical Quality (30%), and Innovation (30%) with qualitative critique feedback.
• Peer Isolation Self-Test: A dedicated audit tool allowing judges to test and verify that cross-judge queries are actively rejected with HTTP 403 Forbidden.

2.2 For Organizers (/dashboard/organizer & /manage-evaluations)

• 100% Dynamic Judge Evaluation Progress: Real-time PostgreSQL aggregation tracking:
  • 30 registered evaluators, 130 submitted evaluations, and 63% overall completion.
  • Active vs. pending evaluators and individual queue bottlenecks.
  • Interactive project score breakdown and evaluator critiques.
• Algorithmic Round-Robin Auto-Assignment: A single-click distribution engine that balances judges evenly across all event tracks ($J \pmod T$).
• Custom Rubric Weights: Live adjustment of evaluation criteria percentages with instant recalculation.
• Score Matrix CSV Export: Instant generation and download of the official RFC-4180 score and ranking matrix via /api/export.csv.
• Deep-Linked URL Navigation: Every sidebar item uses a permanent, bookmarkable URL (/manage-events, /manage-judges, /hackathon-judges, /manage-evaluations, etc.).

2.3 For System Administrators (/admin)

• System Diagnostics: Real-time CPU, RAM, database connection pool, and storage monitoring.
• Immutable Audit Trail: Append-only log of every security event, evaluation submission, role assignment, and deadline transition.
• Database Lifecycle Management: Seed fixture verification and maintenance.

2.4 For Participants & Public Visitors (/, /hackathons, /projects, /results)

• Public Showcase & Gallery: Fluid browsing with multi-attribute search and track filters.
• Submission Portal: Structured submissions with problem statements, repo links, demo URLs, and team rosters.
• Strict Deadline Gating: Automatic submission lockout the exact second an event's submissions_close timestamp passes.
• Digital Certificates: Cryptographically verifiable completion and track winner certificates (/certificates).
• Community Voting: Anti-sybil community upvoting and project discussions.

3. How We Built It (Architecture & Technology Stack)

DOGFOOD is engineered as a monolithic single-container appliance designed for zero-network resilience:

3.1 System Architecture Topology

graph TB
  subgraph Client["Client Browser / Evaluator Devices"]
    Browser["Client Browser (Port 8080)"]
  end

  subgraph Appliance["DOGFOOD Single-Port Docker Appliance (Port 8080)"]
    subgraph Gateway["Frontend Gateway Layer"]
      NextJS["Next.js 16 (App Router + Turbopack)<br/>React 19 Light UI System"]
      Proxy["Internal Reverse Proxy (/api/v1/*)"]
    end

    subgraph Backend["FastAPI Asynchronous Engine (Port 8000)"]
      Router["FastAPI REST Router"]
      AuthGuard["Auth & Session Guard"]
      ZeroTrust["Zero-Trust Peer Isolation Guard"]
      BayesEngine["Empirical Bayes Calibration Engine"]
      AuditService["Security Audit Service"]
    end

    subgraph Database["PostgreSQL 15 Relational Store (Port 5432)"]
      Postgres[("PostgreSQL 15 Local Daemon")]
      UsersTable["users & sessions"]
      EventsTable["events & tracks"]
      ProjectsTable["projects & submissions"]
      ScoresTable["scores & rubrics"]
      AuditTable["audit_logs"]
    end
  end

  Browser --> NextJS
  NextJS --> Proxy
  Proxy --> Router
  Router --> AuthGuard
  AuthGuard --> ZeroTrust
  ZeroTrust --> BayesEngine
  ZeroTrust --> AuditService
  BayesEngine --> Postgres
  AuditService --> Postgres
  Postgres --> UsersTable
  Postgres --> EventsTable
  Postgres --> ProjectsTable
  Postgres --> ScoresTable
  Postgres --> AuditTable

• Frontend Gateway (Next.js 16 + React 19):
  • Serves user traffic on port 8080.
  • Proxies /api/v1/* requests internally to FastAPI on 127.0.0.1:8000.
  • Clean light design system with zero pitch-black background boxes, fluid containers, and responsive sticky sidebars.
• Backend API (FastAPI + Python 3.11):
  • High-concurrency async REST API running on internal port 8000.
  • Custom dependency injection guards (require_auth, require_judge, require_organizer, require_admin).
  • Zero-Trust Peer Isolation middleware.
• Database Core (PostgreSQL 15):
  • Embedded local PostgreSQL instance listening on internal loopback 127.0.0.1:5432.
  • Relational schema with index optimization, constraints, and audit logging.
• Orchestration (entrypoint.sh + Docker):
  • Automatically initializes Postgres cluster, seeds deterministic fixtures, verifies backend readiness, and launches Next.js as PID 1.
  • Starts cleanly with a single command: docker compose up --build.

3.2 Zero-Trust Peer Isolation Sequence

sequenceDiagram
  autonumber
  actor JudgeA as Judge Tomas (jdg_01)
  actor JudgeB as Judge Wei (jdg_02)
  actor Org as Organizer
  participant Gateway as Next.js Gateway (8080)
  participant Guard as Peer Isolation Guard
  participant DB as PostgreSQL Core
  participant Audit as Audit Logger

  Note over JudgeA, DB: 1. Legitimate Score Submission
  JudgeA->>Gateway: POST /api/v1/judge/scores { project: "prj_01", criteria: {...} }
  Gateway->>Guard: Validate session token (jdg_01)
  Guard->>DB: Upsert score record (judge=jdg_01, project=prj_01)
  Guard->>Audit: Log "score.submitted"
  DB-->>Gateway: Score ID 131 persisted
  Gateway-->>JudgeA: 201 Created (ScoreOut)

  Note over JudgeB, DB: 2. Cross-Judge Peer Inspection Attempt
  JudgeB->>Gateway: GET /api/v1/judge/scores?judge=jdg_01
  Gateway->>Guard: Inspect requested judge vs session (jdg_02 != jdg_01)
  Guard->>Audit: Log "peer_isolation_violation_attempt"
  Guard-->>Gateway: PeerIsolationViolationException
  Gateway-->>JudgeB: 403 Forbidden ("Zero-trust barrier: inspection denied")

  Note over Org, DB: 3. Authorized Organizer Progress Monitoring
  Org->>Gateway: GET /api/v1/judge/scores/progress
  Gateway->>Guard: Verify role == "organizer" (is_organizer=True)
  Guard->>DB: Query aggregated counts across all judges
  DB-->>Gateway: 30 judges, 130 scores, 63% completion
  Gateway-->>Org: 200 OK (Full Live Evaluation Matrix)

3.3 Relational Database Entity Model

erDiagram
  USERS ||--o{ SESSIONS : "owns"
  USERS ||--o{ PROJECTS : "submits"
  USERS ||--o{ AUDIT_LOGS : "triggers"
  EVENTS ||--o{ TRACKS : "contains"
  EVENTS ||--o{ PROJECTS : "hosts"
  TRACKS ||--o{ PROJECTS : "categorizes"
  JUDGES ||--o{ SCORES : "grades"
  PROJECTS ||--o{ SCORES : "evaluated_in"

  USERS {
    string id PK
    string email UK
    string name
    string role
    string hashed_password
  }
  EVENTS {
    string id PK
    string slug UK
    string name
    timestamptz submissions_close
    string status
  }
  PROJECTS {
    string id PK
    string slug
    string team
    string track
    string title
    timestamptz submitted_at
  }
  SCORES {
    int id PK
    string judge FK
    string project FK
    json criteria
    text comment
    timestamptz created_at
  }
  JUDGES {
    string id PK
    string name
    string email
    json tracks
  }

4. Key Mathematical & Algorithmic Innovations

4.1 Empirical Bayes Variance Shrinkage ($k = 2.0$)

Raw score averages fail when judges vary in leniency or when projects receive unequal review counts. DOGFOOD applies an Empirical Bayes shrinkage formula to compute the calibrated posterior mean $\hat{\mu}_i$:

$$\hat{\mu}_i = \frac{n_i \cdot \bar{x}_i + k \cdot \mu_0}{n_i + k}$$

• $\bar{x}_i$: The project's observed raw arithmetic mean.
• $n_i$: The number of evaluations completed for this project.
• $\mu_0$: The global evaluation prior across the entire hackathon.
• $k = 2.0$: Bayesian regularization strength (equivalent to two virtual reviews at the global average).

flowchart TD
  RawScores["Raw Evaluations from Database (scores_table)"] --> CalcRaw["Calculate Raw Project Mean:<br/>x̄_i = (1 / n_i) * Σ x_ij"]
  RawScores --> CalcGlobal["Calculate Global Evaluation Prior:<br/>μ_0 = (1 / N) * ΣΣ x_ij"]
  CalcRaw --> Shrinkage["Apply Empirical Bayes Shrinkage Formula:<br/>μ̂_i = (n_i * x̄_i + k * μ_0) / (n_i + k)<br/>[Regularization: k = 2.0]"]
  CalcGlobal --> Shrinkage
  Shrinkage --> RankProjects["Sort Projects by Calibrated Score (μ̂_i)"]
  RankProjects --> LeaderboardUI["Live Calibrated Leaderboard (/results)"]
  RankProjects --> CSVExport["Official RFC-4180 CSV Matrix (/api/export.csv)"]

Outcome: Outlier bias from a single overly generous or harsh judge is mathematically tempered, while projects with many consistent reviews maintain their true ranking dominance.

4.2 Hackathon Lifecycle & Submission Gate State Machine

stateDiagram-v2
  [*] --> RegistrationOpen: Hackathon Announced
  RegistrationOpen --> TeamFormation: Builders Register & Form Teams
  TeamFormation --> ActiveHacking: Event Start Timestamp Reached
  ActiveHacking --> ProjectSubmitted: Submit Project & Code Repository
  ProjectSubmitted --> ActiveHacking: Edit & Refine before Deadline
  ActiveHacking --> SubmissionsClosed: Deadline Passes (submissions_close)
  SubmissionsClosed --> HardGated: Strict 403 Lockout Enforced
  HardGated --> BlindEvaluation: Evaluators Graded via Isolated Queues
  BlindEvaluation --> ScoreCalibration: Empirical Bayes Normalization (k=2.0)
  ScoreCalibration --> ResultsPublished: Public Leaderboard & CSV Matrix Revealed
  ResultsPublished --> CertificatesGenerated: Digital Certificates Issued
  CertificatesGenerated --> [*]

4.3 Algorithmic Round-Robin Track Assignment

To prevent queue starvation, our auto-assignment engine indexes all registered evaluators and tracks, rotating judge pairs in round-robin fashion:
$$j_{(i + k) \pmod m}$$
This guarantees equal evaluator distribution across tracks without manual spreadsheet juggling.

5. Technical Challenges & How We Overcame Them

5.1 True Backend Peer Isolation vs. "UI-Only" Hiding

• The Problem: Most hackathon projects simply hide peer scores in HTML templates, leaving the underlying API wide open to any judge with curl.
• The Solution: We placed the isolation barrier deep inside JudgingService.get_scores_for_judge. If a judge requests another judge's ID, the backend immediately throws a PeerIsolationViolationException (HTTP 403 Forbidden) and writes a security audit entry.

5.2 Single-Port Offline Appliance Architecture

• The Problem: Running PostgreSQL, a Python API server, and a Node.js web server inside a single container without multi-port exposure or host port conflicts.
• The Solution: Next.js App Router reverse-proxies /api/v1/* internally to 127.0.0.1:8000, while Uvicorn talks to PostgreSQL on 127.0.0.1:5432. The outside world only ever touches port 8080.

5.3 Universal Safe Date & Time Handling

• The Problem: Cross-browser hydration mismatches and "Invalid Date" errors caused by differing ISO string formats and human-friendly ranges.
• The Solution: Implemented a universal date utility (dateUtils.ts) that safely parses ISO 8601 strings, UTC deadlines, and range strings, rendering clean, localized dates without UI crashes.

5.4 100% Dynamic Evaluation Matrix

• The Problem: Many platforms rely on static mock data for judge progress displays.
• The Solution: Engineered dynamic SQL aggregations that query real scores, judges, and projects tables on every request, delivering live progress percentages, review counts, and status pills.

6. Accomplishments We're Proud Of

1. Clean Acceptance Report: All automated test checks in run.py .dogfood.toml pass cleanly with zero failures.
2. 100% Air-Gapped Offline Operation: Can run in an underground bunker with zero Wi-Fi, zero external CDNs, and zero cloud API keys.
3. Flawless Light Theme Design: Replaced legacy dark backgrounds with a polished, accessible light palette, subtle gradients, and intuitive typography.
4. Comprehensive Documentation Suite: 7 complete technical guides in /docs covering Architecture, REST APIs, Database Schema, Scoring Math, User Manual, and Operations.
5. Production Reliability: Deterministic database seeding ensures user profiles and evaluation records persist cleanly across container restarts.

7. What We Learned

• Correctness Over Decorative Breadth: A rock-solid, secure T2 implementation that refuses peer inspection beats a flashy T4 system with porous authorization boundaries.
• Statistical Fairness Matters: Participants care deeply about judging integrity. Demonstrating transparent Empirical Bayes calibration builds trust in the final outcome.
• Offline Constraints Breed Better Architecture: Removing external SaaS dependencies forced us to build cleaner, faster, self-contained software that boots in seconds.

8. What's Next for DOGFOOD

• Pairwise Bradley-Terry Tournament Mode: Allowing judges to compare pairs of projects head-to-head for even faster, lower-friction evaluations.
• Cryptographic Zero-Knowledge Score Commitments: Enabling judges to commit cryptographic hashes of scores before revealing them at deadline.
• Automated Sponsor Prize Smart Contracts: Instant programmatic escrow release to winning team wallets upon final calibrated leaderboard publication.

9. Verification & Quick-Start Guide

Launching the Appliance:

# 1. Clone the repository
git clone https://github.com/Naman-mahi/dogfoodhackathon.git
cd dogfoodhackathon

# 2. Start the single-port appliance
docker compose up --build

# 3. Run the automated acceptance test suite
python run.py .dogfood.toml

Ready-to-Use Test Personas:

Key URLs & Resources:

• GitHub Repository: https://github.com/Naman-mahi/dogfoodhackathon
• Landing Page: http://localhost:8080/
• Dynamic Judge Progress: http://localhost:8080/manage-evaluations
• Calibrated Leaderboard: http://localhost:8080/results
• Interactive Swagger Docs: http://localhost:8080/docs
• CSV Matrix Download: http://localhost:8080/api/export.csv
• Documentation Hub: docs/README.md