minecraft-account-manager/README.md

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 — fail-closed Velocity admission plugin

Requirements

• Node.js 22+
• npm 11+
• Docker with Compose, or PostgreSQL 17+

Local setup

cp .env.example .env.local
docker compose up -d postgres
npm install
npm run db:migrate
npm run dev

Set DISCORD_GUILD_ID and DISCORD_INVITE_URL in .env.local so unauthenticated visitors can reach the Discord server. The HTTPS invite is the most reliable way to open Discord or join; the landing page also offers a discord:// app link.

Open http://localhost:3000.

Validation

npm test
npm run typecheck
npm run lint
npm run build
npm run velocity:build

Database workflow

Always create and apply versioned migrations:

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.

Provision or rotate a Velocity API token after migrating:

npm run plugin:create-credential --workspace @minecraft-account-manager/database -- velocity-main

The token is displayed once and stored only as a SHA-256 hash.

Confirmed product decisions

• PostgreSQL and Drizzle ORM
• Keycloak OIDC for admin access with the minecraft-account-manager-admin role
• Deployment-managed Discord guild ID and invite URL
• 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 for trust boundaries and service responsibilities, and docs/security-review.md for implemented controls and production requirements.