# saolsen/gameplay.computer architecture

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

- Interactive diagram: https://gitdiagram.com/saolsen/gameplay.computer
- Repository: https://github.com/saolsen/gameplay.computer

## Overview

##### Frontend Components
- **Web Interface**: Built with HTMX and DaisyUI, facilitating user interactions for gameplay and agent creation.
- **Web Clients**: Specific components like `web.tsx` in `gameplay_computer/agents` and `matches` handle user interactions and display.

##### Backend Components
- **API Layer**: Powered by Hono, managing requests between frontend and backend services.
- **Game Logic**: Located in the `gameplay/` directory, handling game rules and agent behaviors.
- **Agent Services**: Various agents (`connect4_agent_*.ts`, `poker_agent_*.ts`) implementing AI strategies.

##### Database
- **Turso (SQLite)**: Manages persistent data such as user profiles, game histories, and agent configurations.

##### Infrastructure & Configuration
- **Configuration Files**: `deno.json`, `drizzle.config.ts` for environment setup and database configurations.
- **Migrations**: SQL scripts for database schema management.

##### b. Determine Relationships and Interactions
- **Frontend ↔ API Layer**: The web interface communicates with the API layer to send user actions and receive responses.
- **API Layer ↔ Game Logic**: Handles requests related to game operations, leveraging the game logic for rule enforcement and agent interactions.
- **Game Logic ↔ Agent Services**: The game logic invokes appropriate agent services based on the game and user interactions.
- **API Layer ↔ Database**: Reads and writes data pertaining to users, games, and agents.
- **Configuration & Migration Tools**: Ensure the backend environment and database are correctly set up and maintained.

##### c. Highlight Architectural Patterns and Design Principles
- **Modular Architecture**: Separation of concerns with distinct directories for agents, gameplay logic, and frontend components.
- **MVC Pattern**: Likely employed in the frontend (`Model-View-Controller`) with `web.tsx` as views, controllers handling user input, and models representing game states.
- **Microservices Approach**: Although not fully distributed, the separation of agents can be viewed as distinct services interacting through the API layer.
- **Configuration as Code**: Use of configuration files (`deno.json`, `drizzle.config.ts`) and migration scripts aligns with Infrastructure as Code principles.

##### d. Include Relevant Technologies, Frameworks, or Libraries
- **Deno**: Backend runtime for executing TypeScript and JavaScript.
- **Hono**: Web framework facilitating API development.
- **Turso (SQLite)**: Database solution for data persistence.
- **HTMX**: Enhances frontend interactivity without heavy JavaScript frameworks.
- **DaisyUI (Tailwind CSS)**: Provides pre-designed UI components for rapid frontend development.

##### Elements
- **Clear Labels for Each Component**: Frontend (Web Interface), Backend (API Layer, Game Logic, Agent Services), Database (Turso), Configuration Tools.
- **Frontend**: Blue rectangles.
- **Backend Services**: Green rectangles.
- **Configuration**: Yellow hexagons.

##### Frontend Layer
- **Web Interface (HTMX + DaisyUI)**
- User Dashboard
- Game Play Pages (`web.tsx` components)
- Agent Creation Interface

##### Backend Layer
- **API Server (Hono)**
- Routes for Gameplay
- Routes for Agent Management
- **Game Logic (`gameplay/`)**
- 4 Module
- Poker Module
- **Agent Services (`agents/`)**
- 4 Agents
- MCTS Agent
- Random Agent
- Poker Agents
- All-in Strategy
- Folding Strategy

##### Database
- **Turso (SQLite)**
- User Data
- Game Histories
- Agent Configurations

##### Infrastructure
- **Configuration Files**
- `deno.json`
- `drizzle.config.ts`
- **Migration Tools**
- SQL Scripts
- Migration Metadata

##### External Interfaces
- **Deployment**
- Hosting URL: `https://gameplay.computer`
- **Developer Resources**
- Agent Creation Guide: `https://jsr.io/@gameplay/games`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs
    subgraph "Frontend"
        WebInterface["Web Interface"]:::frontend
        AgentComponents["Agent Components"]:::frontend
        MatchesComponents["Matches Components"]:::frontend
        StaticAssets["Static Assets"]:::frontend
    end
    
    subgraph "Backend"
        APILayer["API Layer"]:::backend
        TaskManagement["Task Management"]:::backend
        TracingLogging["Tracing and Logging"]:::backend
        UserManagement["User Management"]:::backend
        GameLogic["Game Logic"]:::backend
        AgentServices["Agent Services"]:::backend
    end
    
    subgraph "Database"
        DB["(Turso (SQLite))"]:::database
    end
    
    subgraph "Infrastructure"
        DenoConfig["deno.json"]:::config
        DrizzleConfig["drizzle.config.ts"]:::config
        Migrations["Database Migrations"]:::config
    end
    
    %% Connections
    WebInterface --> APILayer
    AgentComponents --> APILayer
    MatchesComponents --> APILayer
    StaticAssets --> WebInterface
    
    APILayer --> TaskManagement
    APILayer --> TracingLogging
    APILayer --> UserManagement
    APILayer --> GameLogic
    APILayer --> DB
    
    GameLogic --> AgentServices
    
    %% Click Events
    click WebInterface "https://github.com/saolsen/gameplay.computer/blob/main/gameplay_computer/web.tsx"
    click AgentComponents "https://github.com/saolsen/gameplay.computer/blob/main/gameplay_computer/agents/web.tsx"
    click MatchesComponents "https://github.com/saolsen/gameplay.computer/blob/main/gameplay_computer/matches/web.tsx"
    click APILayer "https://github.com/saolsen/gameplay.computer/blob/main/main.ts"
    click GameLogic "https://github.com/saolsen/gameplay.computer/tree/main/gameplay/"
    click AgentServices "https://github.com/saolsen/gameplay.computer/tree/main/agents/"
    click Migrations "https://github.com/saolsen/gameplay.computer/tree/main/migrations/"
    click DenoConfig "https://github.com/saolsen/gameplay.computer/blob/main/deno.json"
    click DrizzleConfig "https://github.com/saolsen/gameplay.computer/blob/main/drizzle.config.ts"
    click StaticAssets "https://github.com/saolsen/gameplay.computer/tree/main/gameplay_computer/static/"
    click TaskManagement "https://github.com/saolsen/gameplay.computer/blob/main/gameplay_computer/tasks.ts"
    click TracingLogging "https://github.com/saolsen/gameplay.computer/blob/main/gameplay_computer/tracing.ts"
    click UserManagement "https://github.com/saolsen/gameplay.computer/blob/main/gameplay_computer/users.ts"
    
    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:1px
    classDef database fill:#FF6347,stroke:#000,stroke-width:1px
    classDef config fill:#FFD700,stroke:#000,stroke-width:1px
    
    %% Assign classes
    class WebInterface,AgentComponents,MatchesComponents,StaticAssets frontend
    class APILayer,TaskManagement,TracingLogging,UserManagement,GameLogic,AgentServices backend
    class DB database
    class DenoConfig,DrizzleConfig,Migrations config
```
