How jugpanda/hackkyx-web works
1. System shape
- This repo is a three-part platform for AI-generated browser games:
- landing-page/: the main Next.js 15 product surface and API layer
- build-service/: a separate Python Flask build backend
- demo-game/: a reference Pygame project used as a template/example
- The overall architecture is split between a user-facing TypeScript app and a specialized Python compilation service.
2. Primary user-facing application
- landing-page/ is the central orchestrator. It contains the marketing site, auth flows, dashboard, community pages, game lab, and all HTTP routes.
- It also owns the server-side logic for game creation, publishing, comments, reporting, checkout, Stripe webhooks, and proxying play assets.
3. Core data stores and identity
- Supabase is the main backend platform: PostgreSQL for game/user/community data, Supabase Auth for sign-in, and Supabase Storage for generated/build artifacts and uploaded assets.
- The app uses both client and server Supabase helpers, with middleware for session/auth handling and RLS-backed access control.
- Database schema and migrations are kept in the landing-page/supabase*.sql files and landing-page/supabase/migrations/.
4. Game creation pipeline
- The creation flow starts in the Next.js app through endpoints like generate-config, generate-game-code, generate-sprite, and game CRUD routes.
- AI-generated content is converted into game configuration and code by logic in landing-page/lib/game-generator.ts, promptToConfig.ts, schemas.ts, and related validation/content-filter modules.
- Templates in landing-page/lib/template-games/ and builder abstractions in landing-page/lib/builders/ provide the starting point for generated games.
5. Asynchronous build system
- Game builds are offloaded to build-service/, a Flask service designed to compile Python/Pygame projects into web-playable output using Pygbag.
- The Next.js app triggers build jobs via API routes such as api/games/build, build-demo, and generate-async, then polls build state through generation-status.
- Build outputs are stored externally, likely in Supabase Storage, and exposed back to the frontend for play/publish workflows.
6. Runtime game delivery
- Built games are served as browser assets, with play traffic routed through app/api/play/[...path]/route.ts.
- The public/generated/ directory and public/demo-game/ indicate static hosting of generated or sample game artifacts.
- A dedicated game player component and community pages render the playable experience and associated metadata.
7. Community and social features
- The app includes a social layer with likes, comments, profiles, reports, and browseable community game pages.
- Relevant routes include api/comments/*, api/games/like, api/reports/create, api/admin/reports/action, and community pages under app/community/.
- Admin moderation is separated from normal user flows via admin checks and report-management components.
8. Monetization and subscriptions
- Stripe handles paid plans and customer self-service.
- The integration includes checkout session creation, customer portal access, and webhook processing under app/api/stripe/* and app/api/webhooks/stripe/route.ts.
- Subscription limits and entitlement logic live in landing-page/lib/subscription-limits.ts and helper code under lib/stripe/.
9. Security and platform guardrails
- The repo contains explicit support for rate limiting, content filtering, role checks, and secure storage policies.
- Shared-secret authentication protects the build service, while Supabase RLS and middleware enforce access boundaries.
- Password recovery, admin tooling, and webhook signature verification are all first-class parts of the platform’s security model.
10. Front-end structure
- The UI is built with Next.js App Router, TypeScript, Tailwind, and a component library in landing-page/components/ui/.
- Feature areas are organized by route: auth, dashboard, lab, pricing, settings, templates, and community.
- Reusable feature components like game cards, preview panels, upload dialogs, and auth forms wrap the platform’s main workflows.
11. Build and deployment topology
- The frontend is intended for Vercel, while the build service is deployed separately on Fly.io, Railway, or Render via its own config files.
- Environment variables connect the frontend to Supabase, OpenAI, Stripe, and the build service.
- The architecture is therefore a multi-service SaaS: stateless web frontend plus managed backend services and a specialized compiler worker.
12. Supporting assets and tooling
- demo-game/ provides a minimal playable Pygame example and tools/build_game.py supports local/auxiliary build work.
- Documentation files such as ARCHITECTURE.md, setup guides, and migration SQL files are part of the operational surface and indicate the project is designed to be self-hosted and deployed in stages.
Main entry points: app UI routes · supabase Supabase · games Game API · app.py Build service
Components 17
landing-page
Next.js product app, API layer, and platform logic
- UI routes · Marketing site, auth pages, dashboard, lab, pricing, settings, templates, and community pages
landing-page/app - Game API · Create, update, delete, publish, like, reset, and build orchestration endpoints
landing-page/app/api/games - Generation API · Config, code, and sprite generation endpoints for the game creation flow
landing-page/app/api - Social API · Comments and reports endpoints, including admin moderation actions
landing-page/app/api/comments - Billing API · Checkout session creation, portal access, and webhook handling
landing-page/app/api/stripe - Play proxy · Serves playable game assets and browser runtime paths
landing-page/app/api/play/[...path]/route.ts - Auth flows · Sign-in, sign-up, callback, password reset, and recovery screens
landing-page/app/auth - Game generator · Prompt-to-config, validation, filtering, and code generation pipeline
landing-page/lib/game-generator.ts - Templates · Base game templates and injection helpers used to seed generated games
landing-page/lib/template-games - Builders · Language-specific builder abstractions and registry for generated games
landing-page/lib/builders - Static assets · Generated and demo game files served from the frontend public directory
landing-page/public/generated
build-service
Python Flask compilation backend
- Build service · Standalone Python service that compiles game projects into web-playable output
build-service/app.py - Packaging · Container and deployment configuration for the build worker
build-service/Dockerfile
demo-game
Reference Pygame template
- Demo game · Minimal reference Pygame project used as an example and template
demo-game/main.py
data & infra
Supabase, Stripe, and deployment boundaries
- Supabase · Client/server helpers, middleware, schema, migrations, auth, storage, and RLS-backed data access
landing-page/lib/supabase - Guardrails · Rate limiting, content filtering, role checks, and admin authorization
landing-page/lib - Stripe lib · Subscription limits, config, and helper code for entitlements
landing-page/lib/stripe
Connections 24
- UI routes → Auth flows: uses · Auth pages support sign-in, sign-up, and recovery flows
- UI routes → Game API: calls · Dashboard and lab pages trigger game lifecycle actions
- UI routes → Generation API: calls · Lab flows request config, code, and sprite generation
- UI routes → Social API: renders · Community pages surface comments, likes, and reports
- UI routes → Billing API: starts · Pricing and account flows initiate checkout and portal access
- Game API → Game generator: orchestrates · Game creation endpoints convert prompts into structured game artifacts
- Game generator → Templates: seeds · Generated games start from template game scaffolds
- Game generator → Builders: adapts · Builder registry selects the target runtime and code path
- Game generator → Guardrails: filters · Validation and content filtering protect generated output
- Game API → Build service: triggers · Build and demo-build routes dispatch compilation jobs to the worker
- Generation API → Build service: offloads · Async generation can hand work to the separate build backend
- Game API → Supabase: persists · Game records, status, likes, comments, and publish state live in Supabase
- Social API → Supabase: persists · Comments and moderation data are stored in Supabase
- Billing API → Stripe lib: uses · Checkout and entitlement flows share Stripe helpers and limits
- Billing API → Supabase: syncs · Subscription state and user records are tied back to Supabase
- Auth flows → Supabase: authenticates · Supabase Auth powers sign-in, sign-up, callback, and recovery
- Supabase → Guardrails: enforces · RLS, middleware, admin checks, and rate limits constrain access
- Build service → Demo game: builds from · The worker uses the reference Pygame project as a canonical example
- Build service → Packaging: deploys as · Separate container and platform configs package the build backend
- Build service → Static assets: emits · Compiled outputs are exposed to the frontend for play and publish flows
- Play proxy → Static assets: serves · Play traffic proxies browser-accessible generated assets
- UI routes → Play proxy: loads · Game player views pull runtime assets through the proxy route
- Game API → Play proxy: publishes to · Published games become available through play delivery paths
- Social API → Supabase: reads · Community views read profiles, likes, and game metadata