# jugpanda/hackkyx-web architecture

> Architecture diagram of the GitHub repository jugpanda/hackkyx-web, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jugpanda/hackkyx-web
- Repository: https://github.com/jugpanda/hackkyx-web

## Overview

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: [`landing-page/app`](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app) (UI routes), [`landing-page/lib/supabase`](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/supabase) (Supabase), [`landing-page/app/api/games`](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api/games) (Game API), [`build-service/app.py`](https://github.com/jugpanda/hackkyx-web/blob/main/build-service/app.py) (Build service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_landing_page["landing-page"]
  node_lp_ui["UI routes<br/>next app router"]
  node_lp_api_games["Game API<br/>game routes"]
  node_lp_api_gen["Generation API<br/>ai generation"]
  node_lp_api_social["Social API<br/>community routes"]
  node_lp_api_billing["Billing API<br/>stripe routes"]
  node_lp_play_proxy["Play proxy<br/>asset routing<br/>[route.ts]"]
  node_lp_auth["Auth flows<br/>identity pages"]
  node_lp_gamegen["Game generator<br/>generation logic<br/>[game-generator.ts]"]
  node_lp_templates["Templates<br/>starter games"]
  node_lp_builders["Builders"]
  node_static_assets["Static assets<br/>published output"]
end

subgraph group_build_service["build-service"]
  node_build_api["Build service<br/>flask compiler<br/>[app.py]"]
  node_build_packaging["Packaging<br/>pygbag build"]
end

subgraph group_demo_game["demo-game"]
  node_demo_ref["Demo game<br/>pygame template<br/>[main.py]"]
end

subgraph group_infra_data["data & infra"]
  node_lp_supabase[("Supabase<br/>backend platform")]
  node_lp_security{{"Guardrails<br/>platform safety"}}
  node_lp_stripe_lib["Stripe lib<br/>subscription logic"]
end

node_lp_ui -->|"uses"| node_lp_auth
node_lp_ui -->|"calls"| node_lp_api_games
node_lp_ui -->|"calls"| node_lp_api_gen
node_lp_ui -->|"renders"| node_lp_api_social
node_lp_ui -->|"starts"| node_lp_api_billing
node_lp_api_games -->|"orchestrates"| node_lp_gamegen
node_lp_gamegen -->|"seeds"| node_lp_templates
node_lp_gamegen -->|"adapts"| node_lp_builders
node_lp_gamegen -->|"filters"| node_lp_security
node_lp_api_games -->|"triggers"| node_build_api
node_lp_api_gen -->|"offloads"| node_build_api
node_lp_api_games -->|"persists"| node_lp_supabase
node_lp_api_social -->|"persists"| node_lp_supabase
node_lp_api_billing -->|"uses"| node_lp_stripe_lib
node_lp_api_billing -->|"syncs"| node_lp_supabase
node_lp_auth -->|"authenticates"| node_lp_supabase
node_lp_supabase -->|"enforces"| node_lp_security
node_build_api -->|"builds from"| node_demo_ref
node_build_api -->|"deploys as"| node_build_packaging
node_build_api -->|"emits"| node_static_assets
node_lp_play_proxy -->|"serves"| node_static_assets
node_lp_ui -->|"loads"| node_lp_play_proxy
node_lp_api_games -->|"publishes to"| node_lp_play_proxy
node_lp_api_social -->|"reads"| node_lp_supabase

click node_lp_ui "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app"
click node_lp_api_games "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api/games"
click node_lp_api_gen "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api"
click node_lp_api_social "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api/comments"
click node_lp_api_billing "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api/stripe"
click node_lp_play_proxy "https://github.com/jugpanda/hackkyx-web/blob/main/landing-page/app/api/play/[...path]/route.ts"
click node_lp_auth "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/auth"
click node_lp_gamegen "https://github.com/jugpanda/hackkyx-web/blob/main/landing-page/lib/game-generator.ts"
click node_lp_templates "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/template-games"
click node_lp_builders "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/builders"
click node_lp_supabase "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/supabase"
click node_lp_security "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib"
click node_lp_stripe_lib "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/stripe"
click node_build_api "https://github.com/jugpanda/hackkyx-web/blob/main/build-service/app.py"
click node_build_packaging "https://github.com/jugpanda/hackkyx-web/tree/main/build-service/Dockerfile"
click node_demo_ref "https://github.com/jugpanda/hackkyx-web/blob/main/demo-game/main.py"
click node_static_assets "https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/public/generated"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lp_ui,node_lp_api_games,node_lp_api_gen,node_lp_api_social,node_lp_api_billing,node_lp_play_proxy,node_lp_auth,node_lp_gamegen,node_lp_templates,node_lp_builders,node_static_assets toneBlue
class node_build_api,node_build_packaging toneAmber
class node_demo_ref toneMint
class node_lp_supabase,node_lp_security,node_lp_stripe_lib toneRose
```

## Components

### landing-page

Next.js product app, API layer, and platform logic

- [UI routes](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app): next app router · Marketing site, auth pages, dashboard, lab, pricing, settings, templates, and community pages · `landing-page/app`
- [Game API](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api/games): game routes · Create, update, delete, publish, like, reset, and build orchestration endpoints · `landing-page/app/api/games`
- [Generation API](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api): ai generation · Config, code, and sprite generation endpoints for the game creation flow · `landing-page/app/api`
- [Social API](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api/comments): community routes · Comments and reports endpoints, including admin moderation actions · `landing-page/app/api/comments`
- [Billing API](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/api/stripe): stripe routes · Checkout session creation, portal access, and webhook handling · `landing-page/app/api/stripe`
- [Play proxy](https://github.com/jugpanda/hackkyx-web/blob/main/landing-page/app/api/play/[...path]/route.ts): asset routing · Serves playable game assets and browser runtime paths · `landing-page/app/api/play/[...path]/route.ts`
- [Auth flows](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/app/auth): identity pages · Sign-in, sign-up, callback, password reset, and recovery screens · `landing-page/app/auth`
- [Game generator](https://github.com/jugpanda/hackkyx-web/blob/main/landing-page/lib/game-generator.ts): generation logic · Prompt-to-config, validation, filtering, and code generation pipeline · `landing-page/lib/game-generator.ts`
- [Templates](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/template-games): starter games · Base game templates and injection helpers used to seed generated games · `landing-page/lib/template-games`
- [Builders](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/builders): runtime builders · Language-specific builder abstractions and registry for generated games · `landing-page/lib/builders`
- [Static assets](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/public/generated): published output · Generated and demo game files served from the frontend public directory · `landing-page/public/generated`

### build-service

Python Flask compilation backend

- [Build service](https://github.com/jugpanda/hackkyx-web/blob/main/build-service/app.py): flask compiler · Standalone Python service that compiles game projects into web-playable output · `build-service/app.py`
- [Packaging](https://github.com/jugpanda/hackkyx-web/tree/main/build-service/Dockerfile): pygbag build · Container and deployment configuration for the build worker · `build-service/Dockerfile`

### demo-game

Reference Pygame template

- [Demo game](https://github.com/jugpanda/hackkyx-web/blob/main/demo-game/main.py): pygame template · Minimal reference Pygame project used as an example and template · `demo-game/main.py`

### data & infra

Supabase, Stripe, and deployment boundaries

- [Supabase](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/supabase): backend platform · Client/server helpers, middleware, schema, migrations, auth, storage, and RLS-backed data access · `landing-page/lib/supabase`
- [Guardrails](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib): platform safety · Rate limiting, content filtering, role checks, and admin authorization · `landing-page/lib`
- [Stripe lib](https://github.com/jugpanda/hackkyx-web/tree/main/landing-page/lib/stripe): subscription logic · Subscription limits, config, and helper code for entitlements · `landing-page/lib/stripe`

## Connections

- 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
