# 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

```bash
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

```bash
npm test
npm run typecheck
npm run lint
npm run build
npm run velocity: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.

Provision or rotate a Velocity API token after migrating:

```bash
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`](docs/architecture.md) for trust boundaries and service responsibilities, and [`docs/security-review.md`](docs/security-review.md) for implemented controls and production requirements.