# jhoncr/simple-chess architecture

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

- Interactive diagram: https://gitdiagram.com/jhoncr/simple-chess
- Repository: https://github.com/jhoncr/simple-chess

## Overview

1. Backend – This includes Firebase Cloud Functions (written in TypeScript) which are responsible for game logic such as creating games, making moves, and quitting games, along with the corresponding configuration files (firestore.rules, firestore.indexes.json, and various Firebase config files). The “backend/functions/src” directory holds the core logic for these Cloud Functions.
2. Frontend – This is implemented as a React (Next.js) application. It handles user interactions, game state presentation, authentication (via components like auth_handler.tsx), and user interface (components in the “frontend” directory such as Board.tsx, ShareCard.tsx, and various UI components).
3. Database – Firestore is used to store game states. The game data is organized in a collection (named “games”) where each document represents a chess game. The schema includes properties like game state (in FEN format), player details, and metadata such as creation or finish timestamps.

- Client/Frontend (React/Next.js): Represent the web app components including user login, game board, and other UI elements.
- Backend (Firebase Cloud Functions): Highlight functions such as “init_game.ts”, “make_move.ts”, and “quit_game.ts” with emphasis on how they handle requests from the frontend.
- Database (Firestore): Represent the Firestore instance holding the “games” collection where game states and player details are managed.
- External Services: Optionally, note Google Authentication (for user identities) since the player IDs are taken from Google auth tokens.

B. Define the relationships and interactions:
- The frontend sends requests (calls) to the backend Cloud Functions to modify the game state (e.g., starting a game, making a move, quitting).
- The backend, upon processing these calls, interacts with the Firestore database—writing or reading game documents.
- From Frontend to Backend: API requests like “start game”, “make move”.
- From Backend to Database: Reading/updating the game state.

C. Highlight architectural patterns and design principles:
- Separation of Concerns – The system clearly separates presentation (frontend), business logic (backend), and data persistence (Firestore).
- Serverless Functions – The backend leverages Firebase Cloud Functions that provide on-demand execution.
- Real-time Database updates – The Firestore database is structured to update game state in a reactive style appropriate for an interactive chess game.
- Modularization – Notice the clear folder structure with dedicated directories for the functions, components, authentication, and configuration.

D. Include relevant technologies:
- Frontend: Next.js, React, Tailwind CSS (as seen in “tailwind.config.ts”), and TypeScript.
- Backend: Firebase Cloud Functions (TypeScript), guided by ESLint configuration files.
- Database: Firestore, together with Firestore security rules and indexes.
- Additional configurations and deployment files like .firebaserc and firebase.json for both backend and frontend ensure seamless integration with Firebase.

- If desired, include a user authentication component to show Google Auth integration.

- Clear, unambiguous labels for each component.
- Notes or legends that reference important configuration files (like tsconfig.json, package.json) if they are critical to understanding the build and deployment workflow.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (React/Next.js)"
        LandingLayout["Landing Layout"]:::frontend
        LandingPage["Landing Page"]:::frontend
        LoginPage["Login Page (Auth)"]:::frontend
        AuthHandler["Auth Handler"]:::frontend
        GamePage["Game Page"]:::frontend
        GameBoard["Game Board"]:::frontend
        ShareCard["Share Card"]:::frontend
        LandingLayout --> LandingPage
        LandingPage --> LoginPage
        LandingPage --> GamePage
        GamePage --> GameBoard
        GamePage --> ShareCard
        LoginPage --> AuthHandler
    end

    subgraph "Backend (Firebase Cloud Functions)"
        index["index.ts - Main Entry"]:::backend
        init_game["init_game"]:::backend
        make_move["make_move"]:::backend
        quit_game["quit_game"]:::backend
        index --> init_game
        index --> make_move
        index --> quit_game
    end

    subgraph "Database (Firestore)"
        Firestore["Firestore - games collection"]:::database
        firestore_rules["firestore.rules"]:::database
        firestore_indexes["firestore.indexes.json"]:::database
    end

    subgraph "External Services"
        GoogleAuth["Google Authentication"]:::external
    end

    %% Interactions
    LandingPage -- "API_call" --> index
    GamePage -- "API_call" --> index
    LoginPage -- "Uses" --> GoogleAuth
    init_game -- "DB_update" --> Firestore
    make_move -- "DB_update" --> Firestore
    quit_game -- "DB_update" --> Firestore
    Firestore -- "RealtimeListener" --> LandingPage

    %% Styles
    classDef frontend fill:#ccf,stroke:#333,stroke-width:2px;
    classDef backend fill:#cfc,stroke:#333,stroke-width:2px;
    classDef database fill:#fcc,stroke:#333,stroke-width:2px;
    classDef external fill:#fc9,stroke:#333,stroke-width:2px;

    %% Click Events - Frontend
    click LandingLayout "https://github.com/jhoncr/simple-chess/blob/main/frontend/app/(landing)/layout.tsx"
    click LandingPage "https://github.com/jhoncr/simple-chess/blob/main/frontend/app/(landing)/page.tsx"
    click LoginPage "https://github.com/jhoncr/simple-chess/blob/main/frontend/app/login/page.tsx"
    click AuthHandler "https://github.com/jhoncr/simple-chess/blob/main/frontend/lib/auth_handler.tsx"
    click GameBoard "https://github.com/jhoncr/simple-chess/blob/main/frontend/app/(protected)/u/game/components/Board.tsx"
    click ShareCard "https://github.com/jhoncr/simple-chess/blob/main/frontend/app/(protected)/u/game/components/ShareCard.tsx"
    click GamePage "https://github.com/jhoncr/simple-chess/blob/main/frontend/app/(protected)/u/game/page.tsx"

    %% Click Events - Backend
    click init_game "https://github.com/jhoncr/simple-chess/blob/main/backend/functions/src/init_game.ts"
    click make_move "https://github.com/jhoncr/simple-chess/blob/main/backend/functions/src/make_move.ts"
    click quit_game "https://github.com/jhoncr/simple-chess/blob/main/backend/functions/src/quit_game.ts"
    click index "https://github.com/jhoncr/simple-chess/blob/main/backend/functions/src/index.ts"
    click firestore_rules "https://github.com/jhoncr/simple-chess/blob/main/backend/firestore.rules"
    click firestore_indexes "https://github.com/jhoncr/simple-chess/blob/main/backend/firestore.indexes.json"
    click firebaserc "https://github.com/jhoncr/simple-chess/blob/main/backend/.firebaserc"
    click firebase "https://github.com/jhoncr/simple-chess/blob/main/backend/firebase.json"
```
