

DXRating
A web application for maimai DX (music arcade game) providing rating calculators, song data, and community features such as tags, comments, and aliases.
Usage


Architecture
This is a Turborepo monorepo using pnpm as the package manager.
apps/
โโโ web/ React 19 + Vite SPA (UnoCSS, MUI, wouter, TanStack Query)
โโโ backend/ Hono API server (oRPC, Drizzle ORM, PostgreSQL, Better Auth)
โโโ functions/ Cloudflare Workers (edge endpoints)
packages/
โโโ dxdata/ Pre-annotated maimai DX song & sheet metadata
โโโ tsconfig/ Shared TypeScript base configuration
scripts/
โโโ annotator/ Generates annotated song metadata from various sources
Apps
-
apps/web โ The main frontend, serving both web and iOS (via WKWebView) variants. Built with React 19, Vite, UnoCSS, Material-UI 5, and shadcn/ui. Supports 4 languages (en, ja, zh-Hans, zh-Hant) via i18next, with an in-browser SQLite database (sql.js) for offline song data.
-
apps/backend โ The API server built on Hono. Uses oRPC for type-safe API contracts (defined with Zod), Drizzle ORM with PostgreSQL 16 for persistence, and Better Auth for authentication (email/password, Google/GitHub OAuth, passkeys).
-
apps/functions โ Cloudflare Workers edge functions built on Hono, mirroring select backend endpoints for lower latency.
Packages
-
packages/dxdata โ The legacy compatibility snapshot and TypeScript
helpers. New native clients read the published catalog API; this package
remains while existing web and renderer consumers migrate.
-
packages/tsconfig โ Shared TypeScript configuration used across all apps and packages.
Published catalog API
GET /api/v1/dxdata returns the complete current catalog and its metadata in
one schema-versioned, null-free document. The producer stores immutable bodies
in PostgreSQL and atomically advances the production-v1 pointer; the API never
reconstructs the document per request or exposes stored provenance.
The backend reads dxdata.catalog_publications, dxdata.catalog_snapshots, and
dxdata.catalog_build_runs; identity translation joins the current
dxdata.catalog_run_songs and dxdata.catalog_run_sheets memberships to
dxdata.canonical_songs, dxdata.canonical_sheets, and
dxdata.song_source_mappings.
The endpoint supports GET, metadata-only HEAD, strong ETag validators,
and If-None-Match. Successful responses are public and use separate browser
and CDN stale-while-revalidate policies. Errors are no-store. Cloudflare
Cache Rules for the catalog and arcade-catalog paths are owned by the
infrastructure Terraform repository, leaving this application repository with
a single deployment authority.
Tech Stack
| Layer | Technology |
|---|
| Frontend | React 19, Vite, UnoCSS, MUI 5, wouter, TanStack Query |
| Backend | Hono, oRPC, Drizzle ORM, PostgreSQL 16, Better Auth |
| Edge | Cloudflare Workers, Hono |
| Language | TypeScript 5.9, ESM throughout |
| Monorepo | Turborepo, pnpm 10 |
| Linting | oxlint + oxfmt |
| Testing | Vitest |
| Observability | PostHog, Sentry |
Prerequisites
- Node.js 26.12.1
- pnpm 10.30.3+
- Docker (for running PostgreSQL locally)
Getting Started
Install dependencies
Set up the database
pnpm --filter @gekichumai/backend db:up
Copy the example env files and fill in the required values:
cp apps/backend/.env.example apps/backend/.env.local
Key variables:
DATABASE_URL โ PostgreSQL connection string (default: postgres://postgres:postgres@localhost:5432/dxrating)
BETTER_AUTH_SECRET โ Auth secret key
Start development servers
This starts all apps concurrently:
Build
pnpm lint
pnpm lint:fix
pnpm format
pnpm format:check
Run tests
pnpm --filter @gekichumai/backend test
pnpm --filter @gekichumai/dxrating-web test
Deployment
- Web โ Cloudflare Pages
- Backend โ Docker container deployed via Coolify
- CI/CD โ GitHub Actions auto-tags versions on push to
main and triggers deployments
Useful Links
License
The code is MIT. The dxdata song and chart data (packages/dxdata, /api/v1/dxdata) is free to use, and credit is appreciated: "Data from DXRating (dxrating.net)". See the data notice. Song titles, artwork and charts belong to SEGA and their rights holders.
Security
If you find a vulnerability in the repository, please email the organization owner (vulnerability@dxrating.net). We kindly ask you not to disclose the detail of the vulnerability to the public before we have released a fix. Thanks for making DXRating a better site!
Contributors
This project is made possible by the following contributors. Contributions are always welcome!

