Hakutaku¶
Welcome. Hakutaku is the backend for the Fabled plugin — a self-hosted service that does roughly what Microsoft's PlayFab does: store telemetry plus the user, player and character data a game needs, and hand it back over HTTP.
If you have just been handed this repo, read Setup first, get it running, then come back here and pick a page.
This wiki is hosted
Live at https://docs.51.79.242.169.nip.io, served from master — no
tunnel and no local setup needed to read it. To run it locally with live
reload, see Mode C.
What it actually is right now¶
Three things in Docker containers:
| Piece | What it is | Where it lives |
|---|---|---|
| Server | ASP.NET Core 10 minimal API | server/ |
| Web UI | Vue 3 admin panel, served by the server | web/ |
| Database | PostgreSQL 18 via EF Core | migrations in server/Migrations/ |
| Caddy | Reverse proxy, the only public door | caddy/Caddyfile |
It is an early scaffold, and the docs say so wherever it matters. Three
entities exist (Player, Character, TelemetryEvent), admin login works,
and a production stack runs on the DigiPen team43 VM with Jenkins redeploying
on every merge to master. There is no player-facing auth yet, no test suite,
and two directories (sdk/, simulator/) are deliberate placeholders.
The honest status line
Everything under Components describes code that exists. Anything planned-but-absent is called out as such, inline. If a page and the code disagree, the code wins — please fix the page.
Site map¶
-
Install Docker, Node and the .NET SDK from nothing, then run the server, the web UI and these docs. Written assuming no prior context.
-
Architecture
Project structure — the repo layout, the tech stack and why each piece was picked. How the pieces talk — the request lifecycle end to end. Practices and exposure — what is public, what is not, and the conventions we hold to.
-
Components
Caddy · Docker · Database · Server · Auth and sessions · Web UI · Simulator · SDK
-
The VM, the Jenkins pipeline, the SSH tunnel, and what to do when a deploy looks like it did nothing.
-
Reference
API — every endpoint, request body and error shape. Contributing — branches, migrations, line endings, house style.
Where to start, by job¶
| You are… | Read, in order |
|---|---|
| Getting it running locally | Setup |
| Adding an API endpoint | Server → Database → API |
| Adding a page to the admin UI | Web UI → Auth and sessions |
| Touching anything security-shaped | Auth and sessions → Practices |
| Debugging prod | Operations → Caddy |
| Wondering why a change didn't deploy | Operations |
Other docs in the repo¶
These are not duplicated here, on purpose:
TODO.md— the roadmap. What's done, what's next, and the reasoning behind decisions already made.CLAUDE.md— a dense architecture brief written for Claude Code, not for humans. Accurate, but deliberately terse.readme.md— a short front door that points back here.