# vscubing/vscubing-next architecture

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

- Interactive diagram: https://gitdiagram.com/vscubing/vscubing-next
- Repository: https://github.com/vscubing/vscubing-next

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD & Deployment Layer
    subgraph "CI/CD & Deployment"
        GHCI["GitHub Actions CI"]:::infra
        GHCD["GitHub Actions CD"]:::infra
        DockerfileNode["Docker & Local DB Setup"]:::infra
        StartDB["Start Database Script"]:::infra
        MigrateScripts["Migration Script"]:::infra
        Dockploy["Dockploy & DigitalOcean"]:::infra
        GHCI --> GHCD --> Dockploy
        Dockploy --> NextServer
        Dockploy --> BD
        DockerfileNode --> StartDB --> MigrateScripts
    end

    %% Frontend Layer
    subgraph "Frontend"
        UI["Next.js App Router & React UI"]:::frontend
        SharedFE["Shared Frontend Components"]:::frontend
        Static["Static Assets"]:::frontend
        UI --> NextServer
        UI --> APIrest
        UI --> TRPCClient
        Static --> UI
    end

    %% Next.js Server Layer
    NextServer["Next.js Server (Bun)"]:::server

    %% API & RPC Layer
    APIrest["API Routes (auth, health, contest ops)"]:::server
    TRPCClient["tRPC Client"]:::server
    TRPCClient --> TRPCServer

    %% Backend Business Logic Layer
    subgraph "Backend"
        TRPCServer["tRPC Server"]:::server
        Routers["tRPC Routers"]:::server
        AuthOAuth["OAuth Integrations"]:::server
        Session["Session Handling"]:::server
        SharedBE["Shared Backend Utilities"]:::server
        Posthog["PostHog Analytics"]:::server
        Scripts["Scripts & Cron Jobs"]:::server
        MigrateTrigger["Contest Cron Trigger"]:::server
        Env["Env & Middleware Configuration"]:::server

        NextServer --> APIrest
        APIrest --> Routers
        NextServer --> TRPCServer
        TRPCServer --> Routers
        Routers --> BD
        Routers --> AuthOAuth
        Routers --> SharedBE
        SharedBE --> Posthog
        SharedBE --> Telegram
        SharedBE --> Scrambler
        AuthOAuth --> Google
        AuthOAuth --> WCA
        Scripts --> TRPCServer
        Scripts --> MigrateTrigger
        MigrateTrigger --> Routers
        Env --> NextServer
    end

    %% Data Layer
    BD["Postgres DB"]:::data
    DrizzleConfig["Drizzle Migrations & Config"]:::data
    DrizzleConfig --> BD
    BD --> S3

    %% External Services
    subgraph "External Services"
        Google["Google OAuth"]:::external
        WCA["WCA OAuth"]:::external
        Scrambler["vscubing-tnoodle"]:::external
        CronSvc["vscubing-cron"]:::external
        S3["S3 Backups"]:::external
        PosthogSvc["PostHog"]:::external
        Telegram["Telegram Notifications"]:::external
    end

    %% Connections to External Services
    Routers --> Google
    Routers --> WCA
    SharedBE --> Scrambler
    SharedBE --> Telegram
    DrizzleConfig --> S3

    %% Click Events
    click UI "https://github.com/vscubing/vscubing-next/tree/main/src/app"
    click SharedFE "https://github.com/vscubing/vscubing-next/tree/main/src/frontend"
    click Static "https://github.com/vscubing/vscubing-next/tree/main/public/landing"
    click Static "https://github.com/vscubing/vscubing-next/tree/main/public/icons"
    click Static "https://github.com/vscubing/vscubing-next/tree/main/public/images"
    click APIrest "https://github.com/vscubing/vscubing-next/tree/main/src/app/api"
    click TRPCClient "https://github.com/vscubing/vscubing-next/tree/main/src/trpc"
    click TRPCClient "https://github.com/vscubing/vscubing-next/tree/main/src/app/api/trpc/[trpc]"
    click Routers "https://github.com/vscubing/vscubing-next/tree/main/src/backend/api/routers"
    click AuthOAuth "https://github.com/vscubing/vscubing-next/tree/main/src/backend/auth/oauth"
    click Session "https://github.com/vscubing/vscubing-next/blob/main/src/backend/auth/session.ts"
    click DrizzleConfig "https://github.com/vscubing/vscubing-next/blob/main/drizzle.config.ts"
    click DrizzleConfig "https://github.com/vscubing/vscubing-next/tree/main/src/backend/db/schema"
    click SharedBE "https://github.com/vscubing/vscubing-next/tree/main/src/backend/shared"
    click Posthog "https://github.com/vscubing/vscubing-next/blob/main/src/backend/posthog.ts"
    click Scripts "https://github.com/vscubing/vscubing-next/tree/main/src/backend/scripts"
    click MigrateTrigger "https://github.com/vscubing/vscubing-next/blob/main/src/app/api/close-ongoing-and-create-new-contest/route.ts"
    click DockerfileNode "https://github.com/vscubing/vscubing-next/tree/main/Dockerfile"
    click StartDB "https://github.com/vscubing/vscubing-next/blob/main/bin/start-database.sh"
    click MigrateScripts "https://github.com/vscubing/vscubing-next/blob/main/bin/migrate-no-legacy.sh"
    click GHCI "https://github.com/vscubing/vscubing-next/blob/main/.github/workflows/ci.yaml"
    click GHCD "https://github.com/vscubing/vscubing-next/blob/main/.github/workflows/cd.yaml"
    click Dockploy "https://github.com/vscubing/vscubing-next/blob/main/README.md"
    click Env "https://github.com/vscubing/vscubing-next/blob/main/.env.example"
    click Env "https://github.com/vscubing/vscubing-next/blob/main/src/middleware.ts"
    click Env "https://github.com/vscubing/vscubing-next/blob/main/next.config.js"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,stroke-width:2px
    classDef server fill:#E6F4EA,stroke:#22863A,stroke-width:2px
    classDef data fill:#FFF5E5,stroke:#D47F0C,stroke-width:2px
    classDef external fill:#F0F0F0,stroke:#6A737D,stroke-width:2px
    classDef infra fill:#F3E5FF,stroke:#6F42C1,stroke-width:2px
```
