# corn323/fan-interactify architecture

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

- Interactive diagram: https://gitdiagram.com/corn323/fan-interactify
- Repository: https://github.com/corn323/fan-interactify

## Overview

##### Project type and purpose
- This is a hybrid full-stack application combining:
- An Electron desktop app (for the streamer’s UI)
- A local Express/TRPC server with Prisma (to orchestrate connections, handle API calls, persist data)
- A Nuxt.js front-end (served over a public ngrok tunnel to audience devices)

##### Main components
a. Electron Desktop App
- Main process (electron/main.ts)
- Renderer process (Vue app in app.vue + components/)
- Preload script (electron/preload.ts) exposing IPC hooks
- QR-code generator & file-picker for custom images
b. Local Server (server/)
- Express + TRPC endpoint layer (server/trpc/)
- Prisma ORM + SQLite/Postgres (server/prisma/)
- IPC bridge (ipcRequestHandler.ts) for pushing events back to Electron
c. Nuxt Interaction Page (interactionPage/)
- Nuxt3 app serving front-end UI for viewers
- tRPC client plugin to send shake payloads to TRPC server
d. Static Deployment Output (liveStickInteractionPage/)
- Prebuilt Nuxt output, mounted into Electron/Express via mklink
e. Ngrok Tunnel (ngrokUrl.json)
- Exposes local server & Nuxt pages to the public Internet
f. Audience Devices
- Mobile browsers that scan QR, load the Nuxt page, and send motion data

##### Relationships and data flows
1. Electron startup → spawns Express/TRPC server on a local port
2. Electron generates ngrok tunnel → obtains a public URL → renders it as a QR code
3. Viewer scans QR → browser opens Nuxt interaction page via the ngrok URL
4. Nuxt front-end establishes a TRPC connection → calls shake/motion endpoints
5. TRPC server receives motion events → writes to Prisma if needed → forwards events via IPC to Electron main
6. Electron main or renderer updates the cheering-stick visuals in real time

##### Architectural patterns & design principles
- Separation of concerns: Desktop UI vs. headless server vs. web client
- Modular TRPC routers (e.g., post.ts, index.ts) for each API domain
- ORM-based persistence (Prisma migrations + schema)
- IPC bridge for internal event propagation (server → electron main)
- Static asset linkage (Nuxt output folder linked into project for easy serving)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Desktop App Layer
    subgraph "Desktop App"
        EM["Main Process\nelectron/main.ts"]:::desktop
        EP["Preload Script\nelectron/preload.ts"]:::desktop
        REN["Renderer Entry\napp.vue"]:::desktop
        COMP["Renderer Components\ncomponents/"]:::desktop
        HTML["Static HTML\nfanInteraction.html"]:::desktop
    end

    %% Server/API Layer
    subgraph "Server/API"
        TRPC["TRPC Setup\nserver/trpc/trpc.ts"]:::server
        Routers["TRPC Routers\nindex.ts, post.ts"]:::server
        IPC["IPC Bridge\nipcRequestHandler.ts"]:::server
        DB["Database (Prisma)\nschema.prisma, migrations/"]:::db
    end

    %% Web Front-end Layer
    subgraph "Web Front-end"
        N_SRC["Nuxt Source\ninteractionPage/app.vue"]:::web
        N_CFG["Nuxt Config\ninteractionPage/nuxt.config.ts"]:::web
        N_PKG["Package Definitions\ninteractionPage/package.json,\ninteractionPage/package-lock.json"]:::web
        N_PUBLIC["Public Assets\ninteractionPage/public/"]:::web
        TRPC_PLUGIN["TRPC Client Plugin\nplugins/trpc.ts"]:::web
    end

    %% Static Nuxt Output
    STATIC["Static Nuxt Output\nliveStickInteractionPage/"]:::web

    %% Public Tunnel
    NGROK["Ngrok Tunnel\nngrokUrl.json"]:::cloud

    %% Audience Device
    DEVICE["Audience Device\nMobile Browser"]:::device

    %% Connections
    EM -->|"spawns Server"| TRPC
    EM -->|"generates Tunnel"| NGROK
    DEVICE -->|"HTTP GET"| N_SRC
    N_SRC -.->|"TRPC call"| TRPC
    TRPC -->|"writes"| DB
    TRPC -.-|"IPC events"| EM
    EM -->|"updates UI"| REN
    TRPC -->|"serves static via mklink"| STATIC

    %% Click Events
    click EM "https://github.com/corn323/fan-interactify/blob/main/electron/main.ts"
    click EP "https://github.com/corn323/fan-interactify/blob/main/electron/preload.ts"
    click REN "https://github.com/corn323/fan-interactify/blob/main/app.vue"
    click COMP "https://github.com/corn323/fan-interactify/tree/main/components/"
    click HTML "https://github.com/corn323/fan-interactify/blob/main/fanInteraction.html"
    click TRPC "https://github.com/corn323/fan-interactify/blob/main/server/trpc/trpc.ts"
    click Routers "https://github.com/corn323/fan-interactify/blob/main/server/trpc/routers/index.ts"
    click Routers "https://github.com/corn323/fan-interactify/blob/main/server/trpc/routers/post.ts"
    click IPC "https://github.com/corn323/fan-interactify/blob/main/server/trpc/ipcRequestHandler.ts"
    click DB "https://github.com/corn323/fan-interactify/blob/main/server/prisma/schema.prisma"
    click DB "https://github.com/corn323/fan-interactify/tree/main/server/prisma/migrations/"
    click N_SRC "https://github.com/corn323/fan-interactify/blob/main/interactionPage/app.vue"
    click N_CFG "https://github.com/corn323/fan-interactify/blob/main/interactionPage/nuxt.config.ts"
    click N_PKG "https://github.com/corn323/fan-interactify/blob/main/interactionPage/package.json"
    click N_PKG "https://github.com/corn323/fan-interactify/blob/main/interactionPage/package-lock.json"
    click N_PUBLIC "https://github.com/corn323/fan-interactify/tree/main/interactionPage/public/"
    click TRPC_PLUGIN "https://github.com/corn323/fan-interactify/blob/main/plugins/trpc.ts"
    click STATIC "https://github.com/corn323/fan-interactify/tree/main/liveStickInteractionPage/"
    click NGROK "https://github.com/corn323/fan-interactify/blob/main/ngrokUrl.json"

    %% Styles
    classDef desktop fill:#ADD8E6,stroke:#000;
    classDef server fill:#90EE90,stroke:#000;
    classDef web fill:#FFA500,stroke:#000;
    classDef db fill:#D3D3D3,stroke:#000,shape:cylinder;
    classDef cloud fill:#E6E6FA,stroke:#000;
    classDef device fill:#FFFFE0,stroke:#000;
```
