How vscubing/vscubing-next works
Project type and purpose
• This is a full-stack web application (built with Next.js 13 on Bun) for virtual speedcubing contests.
• It includes a React-based frontend (app directory + src/frontend), backend logic (src/backend), a Postgres database (managed via Drizzle ORM migrations), and integrations with external services (OAuth, analytics, scramble generator, cron jobs).
File structure to extract architectural components
• Top-level directories/files:
• src/app – Next.js App Router holding pages, layouts, server/client components, and API routes (auth, health, contest operations, trpc).
• src/backend – Business-logic layer: tRPC routers, authentication (Google, WCA), DB schema (Drizzle), shared utilities, scripts (cron, migrations).
• src/frontend – UI components and client-only utilities shared across the app.
• src/trpc – Client and server wiring for type-safe RPC calls.
• drizzle & drizzle.config.ts – Migration scripts & snapshots for the Postgres schema.
• Dockerfile & bin/*.sh – Dev/test DB containers and migration startup scripts.
• CI/CD: GitHub Actions (.github/workflows/ci.yaml, cd.yaml), Dockploy config via README instructions.
Extract architecture details from the README
• Runtime: Bun & Next.js deployed on a DigitalOcean Droplet via Dockploy.
• Database: Postgres with daily S3 backups; Drizzle‐driven schema migrations.
• External services:
• OAuth providers (Google, WCA) for authentication.
• vscubing-tnoodle (scramble generation).
• vscubing-cron (scheduled contest creation).
• PostHog analytics, Telegram notifications.
• S3 for DB backups.
Main components and their relationships
a. Frontend (Browser)
• React UI served by Next.js (SSR/SSG), static landing page assets (public/landing).
• Communicates via HTTP/HTTPS to Next.js server and tRPC endpoints.
b. Next.js Server (Node/Bun)
• Serves React pages and static assets.
• Hosts API Routes: REST-style auth & health checks plus tRPC server endpoints.
• Invokes backend business logic modules in src/backend.
c. Business Logic / tRPC Routers (src/backend)
• Implements contest management, user settings, leaderboards, session handling.
• Uses Drizzle ORM to query/inject into Postgres.
• Integrates with OAuth providers, PostHog, Telegram, and external scramble generator.
d. Database (Postgres)
• Stores users, contests, solves, settings, sessions.
• Migrated via Drizzle scripts.
e. External Services
• OAuth (Google, WCA)
• S3 (backups)
• vscubing-tnoodle (standalone container)
• vscubing-cron (deploys scheduled jobs)
• PostHog, Telegram
Architectural patterns & principles
• Monorepo: clear separation of layers (app, backend logic, shared UI).
• Next.js App Router + API Routes (co-located server/client code).
• tRPC for end-to-end typed APIs.
• Drizzle ORM for migrations and type-safe database access.
• Modularization: shared code in src/frontend and src/backend/shared.
• Infrastructure as Code: Docker + GitHub Actions + Dockploy for CI/CD.