# longwelwind/swords-and-ravens architecture

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

- Interactive diagram: https://gitdiagram.com/longwelwind/swords-and-ravens
- Repository: https://github.com/longwelwind/swords-and-ravens

## Overview

##### Main Components
- Website Component: Built in Python using Django. This part handles user registration, game creation/joining, a REST API for the game server, and chat functionalities.
- Game Server Component: Written in TypeScript using React for the front-end and enlisting a back-end game engine. It manages the actual gameplay and is itself organized into two parts:
– The client/front-end: Located in the “src/client” directory. It contains a large set of UI components (React components, styling, images/sounds, and game-state panels) that manage interaction with the game.
– The server/back-end: Found in “src/server” (and also “src/common” providing all the game state and logic classes). This part implements the game logic, state transitions (using game state modules for different phases of play), and handling of server messages.

##### Internal Sub-Components and Relationships
– UI Components (React with TypeScript, mobx state management, and Bootstrap for styling)
– Game Logic and State Management (inside “src/common”, with modules for different game phases, actions, and order resolutions)
– Server Code (handling connections, game initialization, and managing active users)
- In the Website, besides the core Django application (contained in the “agotboardgame_main” folder), note there are also dedicated areas for:
– The API (located in the “api” folder) that the game server uses
– Chat functionality (with its own “chat” folder) to handle in-game communication
– Django templates, static assets, and additional middleware and URL routing configurations.
- The file tree also shows Docker files, CI/CD configuration, and several build/deployment scripts, indicating containerized deployments and automated builds.

##### Relationships and Interactions
- The Game Server client communicates with the game server back-end, while the final built client is also “placed into” the website (via the provided build script). This shows a one-direction build-time integration.
- Additionally, indicate connections to external resources:
– A PostgreSQL database and a Redis instance (launched via docker-compose) that serve the website.
– Possibly external authentication services (although they are noted to be disabled in local play).

##### Architectural Patterns and Important Tech
- The separation of concerns is clear (front-end/back-end separation in the game server and dedicated website functionality).
- The Django project uses a standard MVC-like approach with models, views, templates, and migrations.
- The game server leverages React components (the “client” folder) and a modular state management design (multiple game state modules in the “src/common” folder); this modularization is key given the game’s complex logic.
- Deployment is containerized via Docker (noted by Dockerfiles and docker-compose configuration).

##### Being Detailed
- The more modules you separate, the better. Considering the detailed file structure, you might want to detail the “game state” segmentation which directs the turn-based logic (e.g., pre-combat, combat, draft phases, and various ability resolutions).
- For the Website, highlight key directories like “agotboardgame_main,” “api,” and “chat” to illustrate responsibilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Overall System
    A["Swords and Ravens Overview"]:::overview

    %% Website Component (Django)
    subgraph "Website (Django)"
        B["Django App"]:::django
        C["REST API"]:::django
        D["Chat Functionality"]:::django
        %% Extra: Templates/Static & Middleware (annotated)
        E["Templates/Static & Admin"]:::django
    end

    %% Game Server Component (TypeScript/React)
    subgraph "Game Server (TypeScript/React)"
        subgraph "Client/Front-end"
            F["React UI Components & Game-State Panels"]:::tsreact
        end
        subgraph "Server/Back-end"
            G["Game Engine & Server-Side Logic"]:::tsreact
            H["Shared Game Logic & State Modules"]:::tsreact
        end
    end

    %% External Services
    I["PostgreSQL Database"]:::external
    J["Redis Instance"]:::external
    K["Docker & CI/CD Pipeline"]:::external

    %% Relationships and Data Flow
    A -->|"includes"| B
    A -->|"includes"| F
    A -->|"includes"| G

    %% Website connections
    B -->|"serves static"| E
    B -->|"provides"| C
    B -->|"hosts"| D
    B -->|"connects to"| I
    B -->|"connects to"| J

    %% Communication flows within Game Server
    F -->|"WebSocket/REST calls"| G
    F -->|"build integration"| B
    C -->|"REST API Call"| G

    %% External Deployment Annotation
    B ---|"containerized deployment"| K
    G ---|"containerized deployment"| K

    %% Click Events
    click B "https://github.com/longwelwind/swords-and-ravens/tree/master/agot-bg-website/agotboardgame_main"
    click C "https://github.com/longwelwind/swords-and-ravens/tree/master/agot-bg-website/api"
    click D "https://github.com/longwelwind/swords-and-ravens/tree/master/agot-bg-website/chat"
    click F "https://github.com/longwelwind/swords-and-ravens/tree/master/agot-bg-game-server/src/client"
    click G "https://github.com/longwelwind/swords-and-ravens/tree/master/agot-bg-game-server/src/server"
    click H "https://github.com/longwelwind/swords-and-ravens/tree/master/agot-bg-game-server/src/common"

    %% Styles
    classDef django fill:#f6d365,stroke:#e09,stroke-width:2px;
    classDef tsreact fill:#a1c4fd,stroke:#3b8d99,stroke-width:2px;
    classDef external fill:#d4fc79,stroke:#96e072,stroke-width:2px;
    classDef overview fill:#fbc2eb,stroke:#f66,stroke-width:2px;
    
    %% Additional styling for arrows can be added if needed.
```
