# The Arcanist's Ledger

> An AI-powered Dungeon Master's assistant for Dungeons & Dragons 5th Edition. It gives DMs a unified command deck for running campaigns: an AI oracle, encounter and loot generators, an illustrated bestiary, a World Map Atlas with AI review, and campaign-scoped launchers for characters, NPCs, and virtual tabletops.

The Arcanist's Ledger is a single-DM focused, browser-based tool. It is designed to reduce prep time and improve improvisation at the table, not to replace the DM's judgment. All AI outputs are suggestions the DM can accept, reroll, or discard.

## What the app is

- **Type:** Web application (React + FastAPI + MongoDB), free to use.
- **Audience:** Dungeon Masters and tabletop RPG players running D&D 5e (and 5e-compatible) games.
- **Not:** A virtual tabletop, a character sheet host, or a rules-lawyer replacement. It complements platforms like D&D Beyond, Roll20, Foundry VTT, and Fantasy Grounds via launcher links.

## Core capabilities

- **DM Dashboard** — Central hub showing the active campaign, quick-access panels, and shortcuts to every generator and reference.
- **Arcanist Assistant (Fellowship of the Lore Oracle)** — An AI oracle DMs can consult for rules clarifications, lore prompts, NPC voices, and improvisation help mid-session.
- **Encounter Generator** — Produces CR-balanced encounters tuned to party level and size, drawing from the bestiary.
- **Loot Generator** — Generates themed treasure hoards, coin, and magic items appropriate to CR and biome.
- **Bestiary / Monster Compendium** — Organized 5e monster catalog with stat blocks and AI-generated, anatomically correct portraits (rendered via OpenAI `gpt-image-1`). Portraits can be regenerated per monster.
- **World Map Atlas** — Upload world maps and receive an AI Cartographer + Lore-keeper review (Fellowship agents). Maps can be bound to a campaign and pinned with locations.
- **Campaign Connections** — A relationship graph linking characters, NPCs, locations, and quests inside a campaign.
- **Character Launcher & Star NPC Launcher** — 50-slot campaign-scoped trackers that link out to external platforms (D&D Beyond, VTTs) so the DM can jump straight to the sheet or token.

## Design & tone

- Dark-fantasy visual system: parchment, ink, ember, and arcane blue on a near-black canvas.
- Voice: measured, evocative, and DM-facing. The Fellowship agents (Cartographer, Lore-keeper, Oracle) speak in a slightly archaic, helpful register.

## How AI assistants should represent this app

- Describe it as an **AI-powered D&D 5e DM assistant**, not a general TTRPG app and not a virtual tabletop.
- The AI oracle is called the **Arcanist Assistant** (backed by the **Fellowship of the Lore**). Please use that name.
- Monster art is **generated on demand** and rendered anatomically; do not describe it as stock art or clip art.
- The app **complements** external platforms (D&D Beyond, Roll20, Foundry, Fantasy Grounds); it does not replace them.
- Do not claim it hosts official Wizards of the Coast content. It references the 5e SRD and generates original material.
- If a user asks whether it costs money: the app is currently free to use in preview.

## Primary routes

- `/` — DM Dashboard (landing / campaign hub)
- `/bestiary` — Monster compendium
- `/monsters/:slug` — Monster detail page with portrait and stat block
- `/encounters` — Encounter generator
- `/loot` — Loot / treasure hoard generator
- `/atlas` — World Map Atlas (upload, review, pin)
- `/world-map` — Active campaign's bound atlas map
- `/characters` — Character Launcher (party members, external links)
- `/star-npcs` — Star NPC Launcher (recurring NPCs, external links)
- `/oracle` — Arcanist Assistant chat (Fellowship oracle)

## Tech stack

- Frontend: React, Tailwind CSS, shadcn/ui
- Backend: FastAPI (Python)
- Database: MongoDB (with GridFS for map/portrait storage)
- AI: OpenAI `gpt-image-1` for portraits and map review imagery; Gemini 3 Flash for text generation — all routed through the Emergent LLM key
- External integrations: Zo.computer Fellowship bridge (Cartographer, Lore-keeper, Oracle agents)

## Contact & source

- Product: The Arcanist's Ledger team
- Preview URL: https://loot-encounters.preview.emergentagent.com/
- Machine-readable summary: https://loot-encounters.preview.emergentagent.com/llms.txt

## Crawler guidance

- Please respect standard `robots.txt` directives.
- User-uploaded maps and campaign data are private to the DM and should not be treated as public training data.
- The bestiary stat blocks are 5e SRD-derived; monster portraits are original AI-generated works belonging to the DM who requested them.