# innocentdiaz/grandquest architecture

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

- Interactive diagram: https://gitdiagram.com/innocentdiaz/grandquest
- Repository: https://github.com/innocentdiaz/grandquest

## Overview

##### Project type and purpose
- This is a back-end API for “GrandQuest,” implemented in Node.js using a monorepo structure.
- It exposes both REST endpoints (via Express) and real-time interfaces (via a SocketServer).
- It embeds a game “engine” module (controllers + in-memory or persisted store) and a “data” module of static game definitions.
- It integrates with external services: PostgreSQL (persistent state), Redis (caching/session), AWS S3 (assets), Discord (notifications), Sentry (error logging).

##### File structure
- Top‐level: config files (.circleci, Procfile), entry point (index.js), monorepo packages/ folder.
- packages/data: static game constants (attacks, items, entities…).
- packages/engine: core game logic (controllers/combatRoom.js, world.js, plus store.js).
- packages/express: HTTP layer—middleware, route handlers (auth, player, forum, leaderboards, devlog), and tests.
- packages/socketServer: WebSocket handlers for combat and shops.
- packages/services: wrappers for AWS SDK, Discord, PostgreSQL pool + migrations, Redis.
- packages/sentry.js: global error‐reporting initializer.

##### README for architecture hints
- Confirms tech stack (Node.js, Express, PostgreSQL, Redis, AWS SDK).
- Describes runtime (dev hot-reload, Mocha/Chai tests).
- Environment variables outline external dependencies (DB, Redis, AWS, JWT, bcrypt).

##### Detail but avoid over-complexity
- Versioned migrations under the PostgreSQL component if desired.
- Detail the layers (transport vs. business vs. persistence) without cluttering with implementation minutiae.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Clients
    Clients["Clients\n(Web/Game)"]:::external

    %% Infrastructure
    LoadBal["Heroku Dyno\n(Procfile)"]:::infra
    click LoadBal "https://github.com/innocentdiaz/grandquest/tree/master/Procfile"
    Entry["Server Bootstrap\nindex.js"]:::internal
    click Entry "https://github.com/innocentdiaz/grandquest/blob/master/index.js"

    %% Transport Layer
    Express["Express HTTP API"]:::service
    click Express "https://github.com/innocentdiaz/grandquest/blob/master/packages/express/index.js"
    Socket["WebSocket Server"]:::service
    click Socket "https://github.com/innocentdiaz/grandquest/blob/master/packages/socketServer/index.js"

    %% Core Modules
    subgraph "Core Modules"
        Engine["Game Engine Module"]:::internal
        Data["Static Data Module"]:::internal
    end
    click Engine "https://github.com/innocentdiaz/grandquest/blob/master/packages/engine/store.js"
    click Engine "https://github.com/innocentdiaz/grandquest/tree/master/packages/engine/controllers/"
    click Data "https://github.com/innocentdiaz/grandquest/tree/master/packages/data/"

    %% Persistence Services
    DB["PostgreSQL"]:::database
    click DB "https://github.com/innocentdiaz/grandquest/tree/master/packages/services/psql/"
    Redis["Redis"]:::database
    click Redis "https://github.com/innocentdiaz/grandquest/blob/master/packages/services/redis.js"

    %% External Integrations
    S3["AWS S3"]:::cloud
    click S3 "https://github.com/innocentdiaz/grandquest/blob/master/packages/services/awsSDK.js"
    Discord["Discord API"]:::cloud
    click Discord "https://github.com/innocentdiaz/grandquest/blob/master/packages/services/discord.js"

    %% Error Reporting
    Sentry["Sentry Error Reporting"]:::sentry
    click Sentry "https://github.com/innocentdiaz/grandquest/blob/master/packages/sentry.js"

    %% Relationships
    Clients -->|HTTP/JSON| LoadBal --> Entry
    Entry -->|require/import| Express
    Entry -->|require/import| Socket

    Express -->|REST calls| Engine
    Socket -->|WS messages| Engine
    Engine -->|reads| Data

    Engine -->|SQL queries| DB
    Engine -->|Redis commands| Redis

    Engine -->|S3 uploads/downloads| S3
    Engine -->|notifications| Discord

    Express -->|errors| Sentry
    Socket -->|errors| Sentry
    Engine -->|errors| Sentry
    Data -->|errors| Sentry
    DB -->|errors| Sentry
    Redis -->|errors| Sentry
    S3 -->|errors| Sentry
    Discord -->|errors| Sentry

    %% Styling
    classDef external fill:#E0E0E0,stroke:#888,stroke-width:1px
    classDef infra fill:#f4f4f4,stroke:#bbb,stroke-width:1px,stroke-dasharray: 5 5
    classDef internal fill:#D0E7FF,stroke:#0366d6,stroke-width:2px
    classDef service fill:#BEE7FF,stroke:#0288D1,stroke-width:2px
    classDef database fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px
    classDef cloud fill:#FFF3E0,stroke:#FB8C00,stroke-width:2px
    classDef sentry fill:#FFCDD2,stroke:#B71C1C,stroke-width:2px,stroke-dasharray: 2 2
```
