# 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.