The Chronicler's Codex

An intelligent, AI-powered Game Master designed to create dynamic and engaging role-playing experiences with minimal setup.
Explore the Frontend Repo » · Explore the Backend Repo »

Table of Contents

1. About The Project
2. Architectural Overview
3. Tech Stack
4. Getting Started
5. Full Environment Setup
6. API Documentation
7. Roadmap
8. License

📖 About The Project

The Chronicler's Codex is a backend project aimed at creating a smart Game Master (GM) that can run narrative-driven role-playing games. The core philosophy is to leverage Large Language Models (LLMs) not just as storytellers, but as reasoning engines that can dynamically adapt the game based on player actions.

This project eliminates the need for extensive preparation typically associated with TTRPGs, allowing a player to jump straight into a unique, responsive adventure defined by a truly interactive game loop.

(back to top)

🏛️ Architectural Overview

This project is built using a pragmatic Hexagonal Architecture (Ports and Adapters) to ensure a clean separation of concerns and high maintainability.

graph TD
    subgraph Infrastructure
        A[Adapters: Web, Persistence, AI]
    end
    subgraph Application
        B[Use Cases, Ports, Services]
    end
    subgraph Domain
        C[Core Models & Rules]
    end

    A -- Calls --> B
    B -- Uses --> C

    style A fill:#2d2d34,stroke:#c3073f,stroke-width:2px,color:#fff
    style B fill:#2d2d34,stroke:#6f2232,stroke-width:2px,color:#fff
    style C fill:#2d2d34,stroke:#4b5d67,stroke-width:2px,color:#fff

Loading

Dependencies always point inwards, from Infrastructure to Application to Domain.

The game's core loop is a stateful, multi-step dialogue between the client and the server, creating an interactive experience.

sequenceDiagram
    participant Player as Player
    participant Client as Client (Frontend)
    participant Backend as Backend (GameService)
    participant AI as AI (LLM)

    Player->>+Client: Submits action text (e.g., "I try to pick the lock")
    Client->>+Backend: POST /api/.../action

    Backend->>+AI: Reason and propose action (sends full game context)
    AI-->>-Backend: Returns JSON { narration, requiredAction }
    Backend-->>-Client: Returns ActionConsequenceDTO

    Note over Client: Displays narration and "Roll Dice" button

    Player->>+Client: Clicks "Roll Dice"
    Client->>+Backend: POST /api/.../resolve
    Note over Backend: Executes dice roll via RulesEngine

    Backend->>+AI: Narrate Outcome (sends mechanical result and game context)
    AI-->>-Backend: Returns JSON { narration, stateUpdates }
    Note over Backend: Applies state updates to DB
    Backend-->>-Client: Returns final ActionConsequenceDTO
    deactivate Client

    Note over Client: Displays narration

Loading

(back to top)

🛠️ Tech Stack

• Backend: Java 24, Spring Boot 3, Spring AI, Spring Data JPA
• Database: PostgreSQL (with jsonb support)
• AI Backend: Configured for any OpenAI-compatible API (defaulting to OpenRouter) and includes a profile for local use with Ollama.
• API Docs: SpringDoc OpenAPI 3 (Swagger UI)
• Build Tool: Apache Maven

(back to top)

🚀 Getting Started

This backend is designed to be flexible. You can run it locally with Ollama for easy testing, or connect it to a cloud-based AI provider like OpenRouter. To get a local copy up and running, follow these simple steps.

Prerequisites

• JDK 24 or later.
• Apache Maven 3.8+.
• Docker (for the PostgreSQL database).

Installation & Configuration

1. Clone the repo:

   git clone https://github.com/Juangr4/chroniclers-codex.git
   cd chroniclers-codex

2. Choose your AI Provider Setup:

   Option A: Cloud API (Recommended - OpenRouter) This is the default configuration. OpenRouter is a service that gives you access to many different models through a single, OpenAI-compatible API.

   • Get a free API Key from OpenRouter.ai.
   • Create a .env file in the root of the project.
   • Add your API key to the .env file:

     OPENAI_API_KEY=YOUR_OPENROUTER_API_KEY

   Option B: Local Setup (Ollama) If you prefer to run the AI model locally.

   • You will need to activate the ollama profile when running the application.

3. Run the application:

   • For Cloud API (Default):

     ./mvnw spring-boot:run

   • For Local Ollama Setup:

     ./mvnw spring-boot:run -Dspring-boot.run.profiles=ollama
     

Spring Boot will automatically start the PostgreSQL database and ollama containers via its Docker Compose support.

(back to top)

🌐 Full Environment Setup

For the complete experience, you need to run both the backend and the frontend.

1. Follow the "Getting Started" steps above to run the backend.
2. Clone and run the frontend client by following the instructions in its repository: ➡️ The Chronicler's Codex - Frontend Repo

(back to top)

📡 API Documentation

This project uses springdoc-openapi to automatically generate API documentation. Once the application is running, you can access the interactive Swagger UI here:

➡️ http://localhost:8080/swagger-ui.html

(back to top)

🗺️ Roadmap

Implemented Features

• Interactive, AI-Driven Game Loop: A multi-step "Reason -> Resolve -> Narrate" flow.
• Structured AI Communication: AI communicates via reliable JSON contracts.
• Session Management API: Full CRUD operations for game sessions.
• Dynamic State Management: Player and world state are updated by AI decisions.
• Robust Error Handling: Custom exception hierarchy and global handler.
• Multilingual Support: Game sessions can be run in different languages via prompt engineering.
• Flexible Configuration: Support for multiple environments and AI providers via Spring Profiles.

Future Goals

• Voice I/O: Implement endpoints to handle voice-to-text and text-to-voice for a more immersive experience.
• AI Image Generation: Add an API to generate images for key scenes, characters, or locations based on the narrative.
• Dynamic Campaign Creation: Allow the AI to generate custom campaigns.
• Dynamic Character Creation: Allow the AI to assist in creating characters tailored to a generated campaign via API calls.
• Advanced AI Memory: Implement a vector database for long-term memory, allowing for more coherent, long-running campaigns by using RAG features to improve game context.

(back to top)

📄 License

Distributed under the MIT license. See LICENSE.md for more information.

(back to top)