Home

D&D Interactive Maps

An interactive map application for Dungeons & Dragons campaigns. Built with React (TypeScript), Django/GraphQL, and PostgreSQL, containerized with Docker.

Features

• Interactive map viewing and editing
• Support for Underdark and Elturel maps (easily extensible to more)
• Edit mode for dungeon masters
• AI-powered map analysis agent to detect missing or mismatched location pins

Tech Stack

• Frontend: React, TypeScript
• Backend: Django, GraphQL (Strawberry/Graphene)
• Database: PostgreSQL
• Infrastructure: Docker, Docker Compose

Getting Started

Prerequisites

• Docker Desktop installed and running
• Copy .env.example to .env and fill in the values:

  cp backend/.env.example backend/.env
  

• Then edit backend/.env with your actual DB_PASSWORD, SECRET_KEY, etc.

Starting the App (Dev)

Running the frontend natively (outside Docker) avoids WSL2 overhead and filesystem polling lag on Windows. Keep the backend and database in Docker, run Vite locally.

Terminal 1 — backend + database:

docker compose up db backend

Terminal 2 — frontend:

cd frontend
npm run dev

Then open http://localhost:3000 in your browser. Backend API/GraphQL is at http://localhost:8000.

Stopping the App

docker compose down

Running Tests

Frontend:

cd frontend
npm test

Backend:

docker-compose exec backend python manage.py test

Map Locations Agent

The analyze_map management command uses Claude vision to scan a map image, compare identified locations against database pins, and report (or auto-create) missing entries.

docker compose exec backend python manage.py analyze_map --map underdark

See the README for full documentation, including all analyze_map flags and test coverage instructions.