feat(core): scaffold account manager platform

2026-08-01 13:03:26 -04:00
commit 9d305e5dc9
36 changed files with 11898 additions and 0 deletions
@@ -0,0 +1,61 @@
+# Minecraft Account Manager
+
+A Discord-first account registry for a private Java Edition Minecraft network. Players link Discord to one or more Minecraft accounts, while a fail-closed Velocity plugin admits only registered accounts.
+
+## Workspace layout
+
+- `apps/web` — Next.js 16 web application and API, styled with Tailwind CSS v4
+- `apps/discord-bot` — discord.js slash-command bot
+- `packages/contracts` — shared Zod contracts and CloudEvents types
+- `packages/database` — PostgreSQL Drizzle schema and versioned migrations
+- `plugins/velocity` — Velocity admission plugin (planned)
+
+## Requirements
+
+- Node.js 22+
+- npm 11+
+- Docker with Compose, or PostgreSQL 17+
+
+## Local setup
+
+```bash
+cp .env.example .env.local
+docker compose up -d postgres
+npm install
+npm run db:migrate
+npm run dev
+```
+
+Open `http://localhost:3000`.
+
+## Validation
+
+```bash
+npm test
+npm run typecheck
+npm run lint
+npm run build
+```
+
+## Database workflow
+
+Always create and apply versioned migrations:
+
+```bash
+npm run db:generate
+npm run db:migrate
+```
+
+Do not use `drizzle push`; it bypasses the reviewed migration history and can cause destructive schema changes.
+
+## Confirmed product decisions
+
+- PostgreSQL and Drizzle ORM
+- Keycloak OIDC for admin access with the `minecraft-account-manager-admin` role
+- Admin-managed Discord guild configuration
+- discord.js bot with `/register` and `/account`
+- Java Edition online-mode accounts only
+- Velocity admission checks are fail closed
+- VPN detection is represented in the schema but may remain disabled in the first release until a provider is selected
+
+See [`docs/architecture.md`](docs/architecture.md) for trust boundaries and service responsibilities.