# shivarora-sykkuno/saw-blades architecture

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

- Interactive diagram: https://gitdiagram.com/shivarora-sykkuno/saw-blades
- Repository: https://github.com/shivarora-sykkuno/saw-blades

## Overview

##### Project Type & Purpose
- This is a full-stack browser-based runner game. The **client** is a React single-page application (Canvas API for rendering) and the **server** is a Node.js/Express REST API with user authentication, score tracking, and activity logging. Data is persisted in a database (e.g., MongoDB via Mongoose).

##### File Structure Analysis
- Top-level:
- `client/` – React app
– `public/` holds static assets (HTML, sounds).
– `src/` holds application code: entry points (`index.js`, `App.jsx`), pages (Login, Register, GamePage, Leaderboard, ActivityLog, Profile), and `styles.css`.
- `server/` – Express API
– `server.js` – main Express app setup.
– `routes/` – REST endpoints (`auth.js`, `score.js`, `activity.js`).
– `middleware/` – `authMiddleware.js` enforces JWT authentication.
– `models/` – Mongoose schemas (`User.js`, `Activity.js`).
- Shared: `.gitignore`, `README.md`.

##### README Insights
- Describes game mechanics, features (power-ups, scoring, audio), and setup (`npm run server` to start Express).

a. Main Components
1. Frontend (Browser)
– React SPA: UI pages, Canvas game engine, asset loader (audio, sprites).
2. Backend API Server
– Express app with three logical layers:
- Routes (REST endpoints for auth, scores, activity)
- Business logic/controllers
- Models (User, Activity)
3. Database
– NoSQL database (MongoDB) storing Users & Activities.
4. External Services (optional)
– Hosting/CDN for static assets, authentication provider (if any).

b. Relationships & Data Flow
- Browser ⟷ REST API over HTTPS
- Login/Register → POST /auth
- Fetch/Submit Score → GET/POST /score
- Fetch Activity Log → GET /activity
- Fetch Profile → GET /user/profile
- API Server ⟷ Database
- Queries & Writes to Users and Activities collections
- Auth Middleware
- Validates JWT on protected routes (score, activity, profile)

c. Architectural Patterns & Principles
- Separation of concerns:
- Client vs. Server vs. Database
- Within server: Models–Routes–Middleware (MVC-lite)
- Stateless RESTful API
- JWT-based authentication and authorization
- Single Page Application with componentized pages

d. Key Technologies
- Frontend: React, Canvas API, HTML5, CSS
- Backend: Node.js, Express, Mongoose (MongoDB)
- Authentication: JSON Web Tokens
- Build & Dev: npm, package.json scripts

##### Detailed Capture of Architectural Elements
- **Canvas Engine** (game loop, rendering)
- **UI Pages** (Login, GamePage, Leaderboard, etc.)
- **Asset Loader** (audio, images)
- **Auth Middleware** (JWT validation)
- **Route Handlers** (`/auth`, `/score`, `/activity`)
- **Data Models** (`User`, `Activity`)
- Optional external services (e.g., static file hosting).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Tier
    subgraph "Frontend Tier" 
        direction TB
        FEReact["Browser (React SPA)"]:::external
        subgraph "React Application" 
            direction TB
            AppComponent["App Component"]:::frontend
            ReactBootstrap["React Entry (index.js)"]:::frontend
            GlobalStyles["Global Styles (styles.css)"]:::frontend
            subgraph "UI Pages" 
                direction TB
                LoginPage["Login Page"]:::frontend
                RegisterPage["Register Page"]:::frontend
                GamePage["Game Page"]:::frontend
                LeaderboardPage["Leaderboard Page"]:::frontend
                ActivityLogPage["Activity Log Page"]:::frontend
                ProfilePage["Profile Page"]:::frontend
            end
            CanvasEngine["Canvas Engine"]:::frontend
            AssetLoader["Asset Loader"]:::frontend
        end
    end

    %% Backend Tier
    subgraph "Backend Tier" 
        direction TB
        ExpressAPI["Express API"]:::backend
        subgraph "Server Modules"
            direction TB
            MainServer["Main Server Setup"]:::backend
            AuthMiddleware["Auth Middleware"]:::backend
            subgraph "Route Handlers"
                direction TB
                AuthRoutes["Auth Routes"]:::backend
                ScoreRoutes["Score Routes"]:::backend
                ActivityRoutes["Activity Routes"]:::backend
            end
            subgraph "Data Models"
                direction TB
                UserModel["User Model"]:::backend
                ActivityModel["Activity Model"]:::backend
            end
        end
    end

    %% Database
    Database[(MongoDB)]:::database

    %% External Services
    CDN["Static Hosting / CDN"]:::external

    %% Connections
    FEReact -->|"POST /auth\nGET/POST /score\nGET /activity\nGET /user/profile"| ExpressAPI
    ExpressAPI -->|Queries & Writes| Database
    FEReact -->|Fetch Assets| CDN

    %% Click Events
    click FEReact "https://github.com/shivarora-sykkuno/saw-blades/tree/main/client/src"
    click AppComponent "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/App.jsx"
    click ReactBootstrap "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/index.js"
    click GlobalStyles "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/styles.css"
    click LoginPage "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/pages/Login.jsx"
    click RegisterPage "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/pages/Register.jsx"
    click GamePage "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/pages/GamePage.jsx"
    click LeaderboardPage "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/pages/Leaderboard.jsx"
    click ActivityLogPage "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/pages/ActivityLog.jsx"
    click ProfilePage "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/src/pages/Profile.jsx"
    click AssetLoader "https://github.com/shivarora-sykkuno/saw-blades/tree/main/client/public"
    click MainServer "https://github.com/shivarora-sykkuno/saw-blades/blob/main/server/server.js"
    click AuthRoutes "https://github.com/shivarora-sykkuno/saw-blades/blob/main/server/routes/auth.js"
    click ScoreRoutes "https://github.com/shivarora-sykkuno/saw-blades/blob/main/server/routes/score.js"
    click ActivityRoutes "https://github.com/shivarora-sykkuno/saw-blades/blob/main/server/routes/activity.js"
    click AuthMiddleware "https://github.com/shivarora-sykkuno/saw-blades/blob/main/server/middleware/authMiddleware.js"
    click UserModel "https://github.com/shivarora-sykkuno/saw-blades/blob/main/server/models/User.js"
    click ActivityModel "https://github.com/shivarora-sykkuno/saw-blades/blob/main/server/models/Activity.js"
    click Dependencies "https://github.com/shivarora-sykkuno/saw-blades/blob/main/server/package.json"
    click Dependencies "https://github.com/shivarora-sykkuno/saw-blades/blob/main/client/package.json"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#333,stroke-width:1px
    classDef database fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px
```
