4Hacks.
4Hacks is a full-lifecycle hackathon platform for organizers, sponsors, judges, and builders. Alongside event operations, it runs an asynchronous four-layer AI system that inspects submitted GitHub repositories for eligibility, coherence, fraud signals, and code-quality risks.
- Role
- Backend Engineer · AI Systems Architect
- Domain
- Hackathon infrastructure · Autonomous repository evaluation · SaaS platform
System at a glance
What the system does
Four-layer autonomous code evaluation
Multi-track hackathon operations
OAuth 2.0 / PKCE identity provider
Billing, messaging, and observability
Architecture flow
From intent to verified state.
- 01
Organizers and builders use the NestJS API for hackathons, teams, submissions, subscriptions, and account workflows.
- 02
PostgreSQL and Prisma store relational state, while Redis supports cache and distributed queue coordination.
- 03
A submitted repository is cloned and prepared asynchronously through BullMQ workers.
- 04
Registered AI analysis layers evaluate evidence in sequence and create a reviewable final report.
- 05
Real-time gateways, Stripe webhooks, and platform telemetry feed user-facing updates and operator diagnostics.
01 / Product engine
A hackathon lifecycle with real operational mechanics
Competition lifecycle
The platform supports multi-track hackathon setup, approval workflows, custom registration and submission forms, allow-lists, extension tracking, tracks, bounties, prizes, and controlled lifecycle transitions from draft through active, archived, or cancelled states.
Teams, roles, and judging
Builders can discover teams, receive invitations, post open roles, and manage applications. Organizers assign judges and use weighted, multi-criterion scoring to support consistent prize decisions.
Subscriptions as a stateful system
Stripe products, prices, checkout flows, feature quotas, and subscription states are coordinated through verified webhook handling rather than treated as a one-time payment integration.
02 / AI evaluation
Repository analysis designed as a reviewable pipeline
Long-running analysis is separated from the request path and broken into layers with their own outcome and rerun behavior.
Layer 1: eligibility
A first pass checks submission rules against repository documentation, demo material, and commit history to identify whether the project meets the competition’s basic requirements.
Layer 2 and 3: coherence and fraud signals
Native tool calls classify source, test, configuration, build, and documentation files for reuse across analysis. A subsequent two-pass check compares stated claims with concrete code artifacts and can deepen inspection when confidence is low.
Layer 4: code quality exploration
A ReAct agent iterates through repository evidence using scoped tools for file listing and reading, commits, contributors, languages, and activity. It surfaces maintainability debt, security concerns, and implementation anti-patterns in a final report.
Extensible layer registry
Each analyzer implements a common contract and is registered at startup, allowing new checks to be introduced without rewriting the orchestration flow. Critical layers can fail fast, while individual layers support rerun and controlled administrative override.
03 / Platform architecture
Modular services with asynchronous boundaries
Domain separation
NestJS modules isolate transport, validation, services, gateways, and data concerns across the hackathon, identity, evaluation, billing, communication, support, and administrative domains.
Queue-backed work
Git clones, recursive repository inspection, multi-pass model inference, and scheduled email are run through BullMQ and Redis workers. This keeps HTTP paths responsive while making expensive work observable and retryable.
Explicit state machines
Hackathons, submissions, subscriptions, and AI analysis runs follow defined transitions. The application therefore knows whether a submission is draft, submitted, under review, approved, or rejected—and whether a model run is pending, running, completed, stopped, or failed.
04 / Identity, money & realtime
Systems that require proof and operational control
OAuth 2.0 identity provider
An in-house authorization server implements authorization-code flow with PKCE S256, client registration, scopes, short-lived access tokens, single-use authorization codes, and token introspection to support secure ecosystem sign-on.
Security and session intelligence
Credential and social authentication are paired with TOTP and email multi-factor flows. Session telemetry supports device-aware, selective, and global session revocation, while Redis-backed sliding-window limits apply policy by account tier.
Webhook integrity
Stripe webhook payloads are verified against the raw body with HMAC signatures. Event identity and subscription state are handled idempotently so retries cannot duplicate subscription effects.
Real-time collaboration
Socket.IO gateways deliver direct messages, typing and read states, community threads, and immediate platform notifications for team invitations, judge activity, and evaluation updates.
05 / Operability
AI cost, risk, and system health made visible
AI FinOps telemetry
Usage records capture prompt and completion tokens, model-specific cost estimates, duration, and error rates by user or organization. Provider credentials are encrypted and providers can be managed without redeploying the platform.
Structured observability
Pino JSON logs include request correlation IDs and rotate predictably. Prometheus metrics expose request latency, route and status counters, and database-query timing for operational monitoring.
Relational model discipline
PostgreSQL and Prisma model the distinct concerns of OAuth clients and tokens, plans and subscriptions, security events, competition state, AI analysis runs, and real-time conversations with relational constraints and targeted indexes.