A modern web application for tracking and analyzing your maimai DX and CHUNITHM scores with friends. Built with Next.js 16, TypeScript, and Tailwind CSS.
| Path | Package | What it is |
|---|---|---|
apps/main |
@tomomai/site |
The main site, API and Discord bot. Each deployment serves one game (maimai DX on port 3000, CHUNITHM on 3001) |
apps/guess |
@tomomai/guess |
The guesser / heardle minigames (port 3002) |
apps/render |
@tomomai/render |
Standalone image-render service (port 8080) |
packages/* |
@tomomai/* |
Shared UI, i18n, security, utils and render-token code |
The local stack runs Postgres, Redis and RustFS (an S3 stand-in for R2) in Docker, while the apps run on your machine with pnpm.
- Node.js 22.18 or later and pnpm (
corepack enablepicks up the pinned version). The ESLint config and the Discord command script import TypeScript files through Node's built-in type stripping. - Docker with Compose v2
makeandopenssl
git clone https://github.com/shedaniel/tomomai.git
cd tomomai
pnpm install
make setup
pnpm dev:maiVisit http://localhost:3000 and use Continue as anonymous user in the sign-in dialog. This dev-only sign-in needs no Discord or X credentials. pnpm dev:chu serves CHUNITHM on port 3001, and SETUP.md explains running both.
make setup does the following:
- Writes
.env.local(with generated secrets), symlinks it toapps/main/.env.local, and createsapps/render/.env.localandapps/guess/.env.local. Existing env files are never overwritten. - Starts Postgres, Redis and RustFS, and creates a public-read
tomomaibucket. - Applies migrations to the
tomomai(main) andguessdatabases. - Seeds each game's song catalogue from its public site (tomomai.lol for maimai DX) and mirrors the catalogue JSON into the local bucket.
| Target | What it does |
|---|---|
make setup |
env + up + migrate + seed. Safe to re-run |
make env |
Create any missing local env files |
make up |
Start the Docker services and create the bucket |
make down |
Stop the Docker services (data is kept) |
make migrate |
Apply main and guess migrations to the local databases |
make seed |
Re-seed songs into the local database and bucket |
make reset |
Delete all local data (database, Redis, bucket) and rebuild it from scratch |
make migrate and make seed always target the Docker services, not whatever .env.local points at. The seed script also refuses to run against a non-local database.
| Service | Default port | Override |
|---|---|---|
apps/main, maimai DX (pnpm dev:mai) |
3000 | — |
apps/main, CHUNITHM (pnpm dev:chu) |
3001 | — |
apps/guess (pnpm guess:dev) |
3002 | — |
apps/render (pnpm render:dev) |
8080 | PORT in apps/render/.env.local |
| Postgres | 5432 | POSTGRES_PORT |
| Redis | 6379 | REDIS_PORT |
| RustFS (S3 API) | 9000 | S3_PORT |
| RustFS console | 9001 | S3_CONSOLE_PORT |
Docker ports bind to 127.0.0.1 only. If a default port is taken, pass the same override to every make call, e.g. make setup POSTGRES_PORT=55432. The generated env files use whatever ports were set when they were first written.
Postgres credentials are tomomai / tomomai. RustFS credentials are tomomai / tomomai-dev-secret.
- Render service: run
pnpm render:devto serve profile exports, last-credit and daily-plays images.make setupgives it the sameRENDER_TOKEN_SECRETasapps/mainand points it at your localapps/mainfor the song catalogue, so keeppnpm dev:mairunning. - Guesser: run
pnpm guess:dev. It reads the song catalogue from your localapps/main, so keeppnpm dev:mairunning. To test "Sign in with tomomai", create an OAuth app at http://localhost:3000/settings/developer and fill inTOMOMAI_OAUTH_CLIENT_IDandTOMOMAI_OAUTH_CLIENT_SECRETinapps/guess/.env.local. - Real OAuth / Discord bot: fill in the Discord or X credentials in
.env.local. See SETUP.md for how to create them.
pnpm dev:mai # maimai DX site with Turbopack
pnpm dev:chu # CHUNITHM site with Turbopack
pnpm guess:dev # Guesser
pnpm render:dev # Render service
pnpm build # Production build of the main site
pnpm lint # ESLint across the workspace
pnpm typecheck # tsc across the workspace
pnpm test # Every package's tests
pnpm db:generate # Generate a migration from apps/main/src/lib/db/schema-pg.ts
pnpm db:studio # Open Drizzle Studio
pnpm tunnel # Expose localhost:3000 via a Cloudflare tunnel
pnpm --filter @tomomai/site discord:register # Register the Discord bot commandsTo change the database schema, edit the schema file and run db:generate, then make migrate to apply it locally. The guess app's schema is apps/guess/src/lib/db/schema.ts; generate its migrations with pnpm --filter @tomomai/guess db:generate.
Commit messages and PR titles follow docs/COMMIT_CONVENTION.md. Logging follows docs/LOGGING.md. docs/MULTI_GAME.md describes how the games share the app.
Production runs as separate deployments:
| Component | Host | Needs |
|---|---|---|
apps/main |
Vercel (one project per game, chosen by FRONTEND_GAME) |
Postgres, Redis, Cloudflare R2, Vercel Edge Config, Discord application |
apps/guess |
Vercel (separate project per variant) | Optional Postgres (its own database) and Redis |
apps/render |
Any long-lived Docker host (Fly, Railway, Cloud Run, Hetzner, ...) | A RENDER_TOKEN_SECRET shared with apps/main |
See SETUP.md for the full guide: environment variables for each app, database migrations, Discord setup, Docker builds, and populating song and event data.
This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.