DND Companion

Local D&D Campaign Manager for the Whole Table

Project Overview

A campaign tool for tabletop D&D sessions that runs on the Dungeon Master's laptop, while players join from their phones over the same Wi-Fi. It brings character sheets, combat, dice, quests, loot, and campaign notes into one place, replacing scattered paper sheets and spreadsheets. No internet, no installs for players, and no build step: one command starts it, and everything works offline at the table.

Key Features

• Laptop hosts, phones join

  Runs on the DM's laptop; players open it on their phones over local Wi-Fi.

• Simple player login

  Players just tap their name, while the DM's admin account stays password-protected.

• Full character sheets

  D&D 5e stats plus mana, stamina, luck, crits, and magic resistance.

• Combat tracker

  Turn order, conditions, and one-tap actions that roll, apply damage, and log it.

• Shared dice log

  Everyone sees each other's rolls, with secret rolls for the DM.

• Gear that counts

  Equipped items add their bonuses everywhere, from the sheet to combat.

• Loot tables

  Weighted drops where luck makes rare items likelier, plus XP and gold sharing.

• Quests & announcements

  Hidden quests to reveal, rewards to hand out, and banners on every phone.

• Live updates

  Dashboards, sheets, and fights refresh on every phone within seconds.

• Rules & notes

  Built-in rule book, Markdown notes, NPCs, sessions, and world info.

• Search everything

  Find campaigns, characters, NPCs, spells, notes, and rules from the sidebar.

• DM-only secrets

  Monsters, loot, and DM notes stay hidden so there are no spoilers.

How a Game Night Plays Out

1. 1

   The DM opens the table

   Start the app on the laptop. The dashboard shows the address players need to join.

2. 2

   Players join from their phones

   Open the link on the same Wi-Fi, tap your name, and your character sheet is ready.

3. 3

   Explore and take quests

   The DM reveals a quest, players accept it, and an announcement pops up on every phone.

4. 4

   Roll for initiative

   The DM starts a fight and turn order appears for everyone. Next turn is one key press.

5. 5

   Take your action

   Pick a skill, spell, weapon, or potion. The app rolls against the target, applies damage, and logs it.

6. 6

   Loot the battlefield

   Roll the loot table, let players grab their items, and split XP and gold across the party.

7. 7

   Rest and recap

   A long rest refills HP, mana, and spell slots. The DM writes the session recap for next time.

Under the Hood

• FastAPI backend

  One process serves a JSON REST API under /api with Pydantic validation, plus the HTML pages that call it.

• MySQL + SQLAlchemy

  A relational schema for campaigns, characters, fights, loot, and quests, versioned with Alembic migrations.

• Game rules as services

  Dice, combat, character stats, encounters, loot, and quests each live in their own service layer.

• No-build frontend

  Jinja templates and vanilla JavaScript. No Node, no bundler, no CDN, so it runs fully offline.

• Local network hosting

  Uvicorn serves the whole LAN, and the dashboard finds the laptop's IP for players to join.

• Live sync

  Phones poll a change counter every few seconds and reload only when something changed.

• Security

  Bcrypt-hashed admin password, cookie sessions, per-campaign DM roles, and safe Markdown rendering.

• Tested & maintainable

  Pytest suite, demo data seeding, a password reset tool, and a readable request log.