# pupupu999/calculater architecture

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

- Interactive diagram: https://gitdiagram.com/pupupu999/calculater
- Repository: https://github.com/pupupu999/calculater

## Overview

##### Project type and purpose
- Type: Full-stack web application (SPA front-end + RESTful back-end)
- Purpose: “Chipin” is a real-time poker‐score tracking app without real money, allowing friends to create/join rooms, input chip counts at game end, and see live updates of individual and aggregate standings (charts, tables, rankings).

##### File structure
Top level:
– client/poker-app: React app (CRA + craco, Next config present but used primarily as SPA)
– server: Node.js/Express API with firebase-admin
– scripts: Data‐migration & reset utilities

client/poker-app highlights:
– public/: static assets & index.html
– src/
- pages/: React pages (CreateRoom, JoinRoom, Ranking, RoomPage, etc.)
- components/: UI widgets (BattleRecord, LineChart, RankingTable, Spinner…)
- contexts/AuthContext.js: user authentication state
- hooks/: custom data‐fetch hooks (useUser, useUsersWithTotalChip)
- utils/api.js, syncUser.js: wrapper around REST calls & user syncing
- firebase.js: Firebase SDK init

server highlights:
– server.js: Express app bootstrap on port 3001
– middleware/authMiddleware.js: verifies Firebase JWT
– routes/auth.js: sign-up/login endpoints
– routes/secure.js: protected game/room management endpoints
– firebase-admin.js: admin SDK init

config & infra files:
– client/.env.development, firebase.json, .firebaserc: Firebase hosting & environment
– CORS note in README for production

##### Extract insights from README
– Features: real-time chip updates, line-chart of score history, sortable history table, global ranking
– Dev setup: `npm run start-all` launches front (3000) + back (3001), mobile access via LAN IP
– Deployment: front on Firebase Hosting, back on Render (adjust CORS)

a. Main components
1. Client Browser (React SPA)
2. Firebase Hosting (serves SPA)
3. Node.js/Express API Server (Render or local)
4. Firebase Services:
– Authentication (email/password)
– Firestore or Realtime Database (rooms, user stats, game records)
5. Utility scripts (offline tasks)

b. Relationships & data flow
- Browser → Firebase Hosting → serves static JS/CSS
- Browser → Firebase Auth SDK → sign-up/sign-in (email/password)
- Browser → Firestore SDK → read/write public game data (rooms, real-time updates)
- Browser → Express API → protected operations (create room, submit chip count)
- Express API → firebase-admin → verify JWT & read/write Firestore
- scripts → firebase-admin → batch operations on Firestore

c. Architectural patterns & design principles
– Client: SPA, Context API for auth, custom hooks for data fetching
– API: RESTful endpoints, middleware for auth, MVC-light (routes + handlers)
– Security: token-based auth with Firebase JWT
– Separation of concerns: UI vs. business logic vs. persistence

d. Key technologies/frameworks
– React, Create React App (craco), Context & Hooks
– Firebase SDK (Auth & Firestore)
– Node.js, Express, firebase-admin
– Charting library for LineChart component
– Hosting: Firebase Hosting (front), Render.com (back)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend (Client)" 
        direction TB
        Browser["Client Browser"]:::client
        HostingStatic["Static Assets & Entry Point\n(index.html)"]:::client
        SPA["React SPA"]:::client
        subgraph "SPA Structure"
            direction TB
            Pages["React Pages"]:::client
            Components["UI Components"]:::client
            AuthCtx["Authentication Context"]:::client
            Hooks["Custom Hooks"]:::client
            Utils["API Utilities"]:::client
            FirebaseClient["Firebase SDK Init"]:::client
            Bootstrap["App Bootstrap"]:::client
        end
    end

    %% Backend Layer
    subgraph "Backend (API Server)"
        direction TB
        Server["Express API Server"]:::api
        FirebaseAdmin["Firebase Admin SDK Init"]:::api
        AuthMW["Auth Middleware"]:::api
        AuthRoutes["Public Auth Routes"]:::api
        SecureRoutes["Protected Game/Room Routes"]:::api
    end

    %% Cloud Services
    subgraph "Cloud Services"
        direction TB
        FH["Firebase Hosting"]:::cloud
        FA["Firebase Auth"]:::cloud
        DB["Firestore Database"]:::cloud
    end

    %% Scripts
    subgraph "Utility Scripts (Offline)"
        direction TB
        Migrate["Data Migration Script"]:::script
        Reset["Results Reset Script"]:::script
    end

    %% Connections
    Browser -->|loads| FH
    FH -->|serves| HostingStatic
    HostingStatic -->|boots| SPA

    SPA -->|uses Auth SDK| FA
    SPA -->|reads/writes| DB
    SPA -->|REST calls| Server

    Server -->|init| FirebaseAdmin
    Server -->|verifies JWT| AuthMW
    Server -->|routes signup/login| AuthRoutes
    Server -->|routes protected ops| SecureRoutes
    AuthMW -->|reads/writes| DB
    AuthRoutes -->|interacts| FA
    SecureRoutes -->|interacts| DB

    Migrate -->|batch ops| FirebaseAdmin
    Migrate -->|writes| DB
    Reset -->|writes| DB

    %% Click Events
    click Browser "https://github.com/pupupu999/calculater/tree/master/client/poker-app/"
    click HostingStatic "https://github.com/pupupu999/calculater/blob/master/client/poker-app/public/index.html"
    click Pages "https://github.com/pupupu999/calculater/tree/master/client/poker-app/src/pages/"
    click Components "https://github.com/pupupu999/calculater/tree/master/client/poker-app/src/components/"
    click AuthCtx "https://github.com/pupupu999/calculater/blob/master/client/poker-app/src/contexts/AuthContext.js"
    click Hooks "https://github.com/pupupu999/calculater/blob/master/client/poker-app/src/hooks/useUser.js"
    click Hooks "https://github.com/pupupu999/calculater/blob/master/client/poker-app/src/hooks/useUsersWithTotalChip.js"
    click Utils "https://github.com/pupupu999/calculater/blob/master/client/poker-app/src/utils/api.js"
    click Utils "https://github.com/pupupu999/calculater/blob/master/client/poker-app/src/utils/syncUser.js"
    click FirebaseClient "https://github.com/pupupu999/calculater/blob/master/client/poker-app/src/firebase.js"
    click Bootstrap "https://github.com/pupupu999/calculater/blob/master/client/poker-app/src/index.js"
    click Server "https://github.com/pupupu999/calculater/blob/master/server/server.js"
    click FirebaseAdmin "https://github.com/pupupu999/calculater/blob/master/server/firebase-admin.js"
    click AuthMW "https://github.com/pupupu999/calculater/blob/master/server/middleware/authMiddleware.js"
    click AuthRoutes "https://github.com/pupupu999/calculater/blob/master/server/routes/auth.js"
    click SecureRoutes "https://github.com/pupupu999/calculater/blob/master/server/routes/secure.js"
    click Migrate "https://github.com/pupupu999/calculater/blob/master/scripts/convertField.js"
    click Reset "https://github.com/pupupu999/calculater/blob/master/scripts/resultsReset.js"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#2B8FEB,color:#0B3D91
    classDef api fill:#FFE2B3,stroke:#FF8C00,color:#A35200
    classDef cloud fill:#DFF7DC,stroke:#34A853,color:#0B6623
    classDef script fill:#F2F2F2,stroke:#A0A0A0,color:#555555
```
