chocoadmin/AGENTS.md

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ before writing any code. Heed deprecation notices.

---

Project: chocoadmin

Admin panel for the chocomae service (mouse-typing), extracted into a standalone Next.js 16 app. It shares the existing MariaDB database — do not modify the DB schema.

Critical rules

• Never alter the DB schema. All tables are shared with the live chocomae service.
• All mutating APIs must verify current Status = 1 before acting (idempotency guard, returns 409 if already processed).
• Wrap every mutation in a transaction: maestro, maestro_extension/maestro_upgrade, and maestro_log must be updated atomically.
• Send email only after a successful commit, never inside the transaction.
• Admin password verification uses MariaDB PASSWORD() function — the existing admin table stores hashed passwords this way. Do not change this without a migration plan.
• Extension approval date calculation happens server-side: if current expiry is in the past, use today +1 year; otherwise use current expiry +1 year.
• Upgrade approval sets AvailableActivateDateTime = NOW() + 1 year. Do not change PlayerCount on upgrade.
• When approving an extension or upgrade, close all other Status = 1 requests for the same MaestroID by setting them to Status = 2, then set the approved request to Status = 3.

Authentication

• NextAuth.js v5 (next-auth@5.0.0-beta.31) with Credentials Provider.
• Config lives in auth.ts (project root), not inside app/.
• Unauthenticated requests are caught by proxy.ts (middleware) and redirected to /login.
• API routes must call auth() and return 401 if no session.

Key files

File	Purpose
auth.ts	NextAuth config (Credentials Provider, MariaDB PASSWORD verify)
proxy.ts	Middleware — redirects unauthenticated users to /login
lib/db.ts	Prisma Client singleton
lib/constants.ts	Status code constants (ACTIVATE_STATUS, ACCOUNT_TYPE, REQUEST_STATUS)
lib/maestros.ts	Maestro DB queries
lib/extension-requests.ts	Extension request queries and approval logic
lib/upgrade-requests.ts	Upgrade request queries and approval logic
prisma/schema.prisma	Generated via prisma db pull — do not hand-edit model fields
docs/business-rules.md	Full reference for existing chocomae business logic

maestro_log conventions

Always record a log entry after a successful DB change. Use these Type values:

Type	When
extension_maestro	Extension approved
cancel_extension_maestro	Extension cancelled (new type, not in original)
upgrade_maestro	Upgrade approved
reject_upgrade_maestro	Upgrade rejected (new type, not in original)
update_maestro_name	Maestro name changed
update_maestro_email	Maestro email changed

Remark column is char(100) — keep values under 100 characters.

Implemented phases (do not re-implement)

• Phase 0–8 are complete: login, maestro list/detail, extension requests, upgrade requests, Docker setup, transaction safety, auth guards.

Planned phases (not yet implemented)

• Phase 9 — Structured logging (lib/logger.ts, correlation IDs, Prisma query logging)
• Phase 10 — Maestro info edit form + student list with pagination (PATCH /api/maestros/[id], GET /api/maestros/[id]/students)
• Phase 11 — Email auto-send via Nodemailer after extension/upgrade approval (lib/mail.ts)

Packages to know

• mariadb + @prisma/adapter-mariadb — Prisma uses the mariadb driver directly (not mysql2)
• @base-ui/react — used instead of Radix UI primitives for shadcn components
• zod v4 — Zod v4 API differs from v3; check docs before writing schemas
• next-auth v5 beta — API surface differs significantly from v4