# jdds97/tic-tac-toe architecture

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

- Interactive diagram: https://gitdiagram.com/jdds97/tic-tac-toe
- Repository: https://github.com/jdds97/tic-tac-toe

## Overview

##### Project type and purpose
- This is a full-stack web application:
– Frontend and backend are built together using Next.js App Router with Server Actions
– Persistent game data and stats stored in MongoDB
– Containerized with Docker/Docker Compose

1. Developer workstation / CI (optional)
– Git repo, ESLint, Jest tests
2. Docker Compose layer
– Node.js “app” service running the Next.js application
– MongoDB service for data persistence
3. Next.js application
A. Frontend Client (React + TypeScript)
– Renders pages under src/app (layout, page.tsx)
– Renders UI components in src/components (GameBoard, GameStats)
– Uses global CSS from src/app/globals.css
B. Backend Server Actions (Next.js API layer)
– Defined in src/lib/actions.ts
– Exposes functions to read/write games and stats
– Validates inputs using TypeScript types in src/lib/types.ts
C. Custom Hooks (client-side calls to server actions)
– useGameState (src/hooks/useGameState.ts)
– useGameStats (src/hooks/useGameStats.ts)
D. Business Logic & Utilities (shared client/server)
– Game logic in src/lib/gameLogic.ts
– Constants and helpers in src/lib/constants.ts, utils.ts
4. Database
– MongoDB collections for Game and Stats models (src/db/models)
– Connection logic in src/db/mongoDb.ts

##### Architectural patterns & design principles
- Monolithic containerized service with clear separation of concerns
- Next.js App Router enforcing server/client boundaries
- Server Actions as thin API endpoints behind the scenes
- Shared code (gameLogic, types) to avoid duplication
- Custom React hooks abstracting data fetching/state

##### Relevant technologies
- Next.js (React, App Router, Server Actions)
- TypeScript for type safety
- MongoDB with Mongoose-style models
- Docker & Docker Compose for environment reproducibility
- Jest for unit testing, ESLint for linting

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation / CI
    subgraph "Developer Workstation / CI"
        style DeveloperWorkstation fill:#ccc,stroke:#333,stroke-width:1px
        GitRepo["Git Repository"]:::infra
        ESLint["ESLint Config"]:::infra
        JestConfig["Jest Config & Setup"]:::infra
        UnitTests["Unit Tests (gameLogic)"]:::infra
    end

    %% Docker Compose layer
    subgraph "Docker Compose"
        style DockerCompose fill:#ddd,stroke:#333,stroke-width:1px
        Orchestrator["docker-compose.yml"]:::infra
        NodeService["Node.js App Service"]:::infra
        MongoService["MongoDB Service"]:::infra
    end

    %% Next.js Application
    subgraph "Next.js Application"
        %% Frontend Client
        subgraph "Frontend Client" 
            style FrontendClient fill:#bbf,stroke:#333,stroke-width:1px
            GlobalStyles["globals.css"]:::frontend
            Layout["layout.tsx"]:::frontend
            Page["page.tsx"]:::frontend
            GameBoard["GameBoard Component"]:::frontend
            GameStats["GameStats Component"]:::frontend
        end

        %% Backend Server Actions
        subgraph "Server Actions"
            style ServerActions fill:#bfb,stroke:#333,stroke-width:1px
            Actions["actions.ts"]:::backend
            Types["types.ts"]:::backend
        end

        %% Custom Hooks
        subgraph "Custom Hooks"
            style Hooks fill:#bbf,stroke:#333,stroke-width:1px
            useGameState["useGameState Hook"]:::frontend
            useGameStats["useGameStats Hook"]:::frontend
        end

        %% Business Logic & Utilities
        subgraph "Business Logic & Utilities"
            style BusinessLogic fill:#bfb,stroke:#333,stroke-width:1px
            GameLogic["gameLogic.ts"]:::backend
            Constants["constants.ts"]:::backend
            Utils["utils.ts"]:::backend
        end
    end

    %% Database Layer
    subgraph "Database"
        style DatabaseLayer fill:#fed,stroke:#333,stroke-width:1px
        MongoConnection["mongoDb.ts"]:::database
        GameModel["Game Model"]:::database
        StatsModel["Stats Model"]:::database
        DBCylinder[(MongoDB)]:::database
    end

    %% Connections
    DeveloperWorkstation -->|deploys| Orchestrator
    Orchestrator -->|runs| NodeService
    Orchestrator -->|runs| MongoService

    GameBoard -->|calls| useGameState
    GameStats -->|calls| useGameStats
    useGameState -->|invokes| Actions
    useGameStats -->|invokes| Actions
    Actions -->|uses| GameLogic
    Actions -->|uses| Constants
    Actions -->|uses| Utils
    Actions -->|connects to| MongoConnection
    MongoConnection -->|operates on| GameModel
    MongoConnection -->|operates on| StatsModel
    GameModel -->|reads/writes| DBCylinder
    StatsModel -->|reads/writes| DBCylinder
    DBCylinder -->|returns data| Actions
    Actions -->|returns| useGameState
    Actions -->|returns| useGameStats
    useGameState -->|updates| GameBoard
    useGameStats -->|updates| GameStats

    JestConfig -->|runs tests on| UnitTests
    UnitTests -->|imports| GameLogic

    %% Click Events
    click GitRepo "https://github.com/jdds97/tic-tac-toe/blob/main/.gitignore"
    click GitRepo "https://github.com/jdds97/tic-tac-toe/blob/main/.gitattributes"
    click ESLint "https://github.com/jdds97/tic-tac-toe/blob/main/eslint.config.mjs"
    click JestConfig "https://github.com/jdds97/tic-tac-toe/blob/main/jest.config.js"
    click JestConfig "https://github.com/jdds97/tic-tac-toe/blob/main/jest.setup.js"
    click UnitTests "https://github.com/jdds97/tic-tac-toe/blob/main/src/__tests__/gameLogic.test.ts"
    click Orchestrator "https://github.com/jdds97/tic-tac-toe/blob/main/docker-compose.yml"
    click NodeService "https://github.com/jdds97/tic-tac-toe/tree/main/Dockerfile"
    click GlobalStyles "https://github.com/jdds97/tic-tac-toe/blob/main/src/app/globals.css"
    click Layout "https://github.com/jdds97/tic-tac-toe/blob/main/src/app/layout.tsx"
    click Page "https://github.com/jdds97/tic-tac-toe/blob/main/src/app/page.tsx"
    click GameBoard "https://github.com/jdds97/tic-tac-toe/blob/main/src/components/GameBoard.tsx"
    click GameStats "https://github.com/jdds97/tic-tac-toe/blob/main/src/components/GameStats.tsx"
    click Actions "https://github.com/jdds97/tic-tac-toe/blob/main/src/lib/actions.ts"
    click Types "https://github.com/jdds97/tic-tac-toe/blob/main/src/lib/types.ts"
    click useGameState "https://github.com/jdds97/tic-tac-toe/blob/main/src/hooks/useGameState.ts"
    click useGameStats "https://github.com/jdds97/tic-tac-toe/blob/main/src/hooks/useGameStats.ts"
    click GameLogic "https://github.com/jdds97/tic-tac-toe/blob/main/src/lib/gameLogic.ts"
    click Constants "https://github.com/jdds97/tic-tac-toe/blob/main/src/lib/constants.ts"
    click Utils "https://github.com/jdds97/tic-tac-toe/blob/main/src/lib/utils.ts"
    click MongoConnection "https://github.com/jdds97/tic-tac-toe/blob/main/src/db/mongoDb.ts"
    click GameModel "https://github.com/jdds97/tic-tac-toe/blob/main/src/db/models/Game.ts"
    click StatsModel "https://github.com/jdds97/tic-tac-toe/blob/main/src/db/models/Stats.ts"

    %% Styles
    classDef infra fill:#ccc,stroke:#333,stroke-width:1px
    classDef frontend fill:#bbf,stroke:#333,stroke-width:1px
    classDef backend fill:#bfb,stroke:#333,stroke-width:1px
    classDef database fill:#fed,stroke:#333,stroke-width:1px
```
