How monkeytypegame/monkeytype works
Purpose and topology
Monkeytype is a customizable typing-test platform with browser-side real-time test execution, optional authenticated accounts, persisted results, leaderboards, social connections, and moderation/admin APIs. It is a pnpm/Turborepo TypeScript monorepo: a Solid/Vite frontend, Express backend, and shared contracts/schemas/packages.
Entry points and composition
• Frontend browser bootstrap and application mount: frontend/src/index.html, frontend/src/ts/index.ts, frontend/src/ts/components/mount.tsx.
• Backend HTTP process: backend/src/server.ts starts the application assembled in backend/src/app.ts.
• HTTP routes are grouped by domain and connect controllers to the API surface: backend/src/api/routes/index.ts, backend/src/api/controllers/result.ts, backend/src/api/controllers/user.ts.
• Background processing is independently initialized through backend/src/workers/index.ts and backend/src/jobs/index.ts.
Typing-test runtime
The frontend owns latency-sensitive typing behavior rather than round-tripping each keystroke. Test setup selects words, quotes, language assets, modes, and modifiers; input listeners/handlers mutate test state; test logic derives live WPM, accuracy, errors, completion, and result data; the UI renders the test and result views.
• Core test lifecycle: frontend/src/ts/pages/test.ts, frontend/src/ts/test/test-logic.ts, frontend/src/ts/test/result.ts.
• Input boundary: frontend/src/ts/input/input-element.ts, frontend/src/ts/input/listeners/input.ts, frontend/src/ts/input/handlers/insert-text.ts.
• Primary test UI: frontend/src/ts/components/pages/test/Monkey.tsx, frontend/src/ts/components/pages/test/TestConfig.tsx.
• Bundled language, layout, quote, challenge, theme, and sound data are served as static frontend assets, e.g. frontend/static/languages/english.json, frontend/static/layouts/qwerty.json, frontend/static/quotes/english.json.
Client state, navigation, and backend boundary
Solid components use domain state/config stores, controllers, collections, and query modules. Configuration persists locally but can be synchronized with server configuration. The typed API boundary is defined once in shared contracts and consumed through ts-rest adapters.
• Client configuration/state: frontend/src/ts/config/store.ts, frontend/src/ts/config/persistence.ts, frontend/src/ts/states/test.ts.
• Navigation and page selection: frontend/src/ts/controllers/route-controller.ts, frontend/src/ts/controllers/page-controller.ts.
• API client and queries: frontend/src/ts/ape/index.ts, frontend/src/ts/queries/index.ts.
• Shared API contract boundary: packages/contracts/src/index.ts, packages/contracts/src/results.ts, backend/src/api/ts-rest-adapter.ts.
Backend request and persistence pipeline
Requests pass middleware for request context, authentication, configuration, authorization, compatibility, rate limits, and errors before domain controllers. Controllers validate/coordinate operations; DAL modules isolate MongoDB/Redis persistence and query behavior.
• Cross-cutting boundary: backend/src/middlewares/context.ts, backend/src/middlewares/auth.ts, backend/src/middlewares/rate-limit.ts.
• Result submission and anti-cheat: backend/src/api/controllers/result.ts, backend/src/anticheat/index.ts, backend/src/dal/result.ts.
• Account, presets, connections, quotes, and admin operations follow equivalent controller-to-DAL domains: backend/src/api/controllers/user.ts, backend/src/dal/user.ts, backend/src/dal/leaderboards.ts.
• Shared Zod-oriented data validation/schema layer: packages/schemas/src/results.ts, packages/schemas/src/users.ts, packages/schemas/src/configuration.ts.
External services and asynchronous work
MongoDB is the durable application store; Redis supports leaderboards, rate-sensitive operations, queues, and Lua-backed result/rank operations. Firebase is initialized client-side and server-side for account/authentication integration. Queues decouple email and deferred work; scheduled jobs refresh leaderboard and operational data.
• Infrastructure initialization: backend/src/init/db.ts, backend/src/init/redis.ts, backend/src/init/firebase-admin.ts.
• Redis leaderboard scripts: backend/redis-scripts/add-result.lua, backend/redis-scripts/get-rank.lua.
• Queues/workers/jobs: backend/src/queues/index.ts, backend/src/workers/email-worker.ts, backend/src/jobs/update-leaderboards.ts.
• Firebase client integration: frontend/src/ts/firebase.ts, frontend/src/ts/auth.tsx.
Deployment and operational boundary
The frontend is built by Vite and served through an Nginx-oriented frontend container; the Node backend is separately containerized. Compose files provision the deployable stack and local backend dependencies.
• Build/runtime configuration: frontend/vite.config.ts, docker/frontend/Dockerfile, docker/backend/Dockerfile.
• Stack definitions: docker/docker-compose.yml, backend/docker/compose.yml.
Main entry points: test-logic.ts Typing-test runtime · result.ts Persistence DAL · Monkey.tsx Test UI · index.ts Typed API client
Components 21
Frontend
Solid/Vite browser application.
- Browser bootstrap
frontend/src/ts/index.ts - Navigation controllers
frontend/src/ts/controllers/route-controller.ts - Test UI
frontend/src/ts/components/pages/test/Monkey.tsx - Typing-test runtime · Computes live typing metrics and final result locally.
frontend/src/ts/test/test-logic.ts - Input handling
frontend/src/ts/input/input-element.ts - Config and test state · Persists local configuration and holds active test state.
frontend/src/ts/config/store.ts - Language and test assets
frontend/static/languages/english.json - Typed API client
frontend/src/ts/ape/index.ts - Firebase client auth
frontend/src/ts/firebase.ts
Shared contracts
Typed API and validation boundary.
- API contracts · Single typed client-server API definition.
packages/contracts/src/index.ts - Validation schemas
packages/schemas/src/results.ts
Backend API
Express request pipeline and domain operations.
- Express server
backend/src/server.ts - Routes and middleware · Applies context, auth, rate limits, and errors before controllers.
backend/src/api/routes/index.ts - Result controller
backend/src/api/controllers/result.ts - User controller
backend/src/api/controllers/user.ts - Anti-cheat
backend/src/anticheat/index.ts
Data and async
Persistence, Redis processing, and background work.
- Persistence DAL · Domain modules isolate application queries and storage behavior.
backend/src/dal/result.ts - MongoDB
backend/src/init/db.ts - Redis · Leaderboard scripts perform result and rank operations.
backend/src/init/redis.ts - Workers and scheduled jobs · Processes queued email and refreshes leaderboard data.
backend/src/workers/email-worker.ts
Deployment
Separate frontend and backend container stack.
- Container stack · Frontend and Node backend are independently containerized.
docker/docker-compose.yml
Connections 27
- Browser bootstrap → Navigation controllers: selects pages
- Browser bootstrap → Test UI: mounts
- Test UI → Config and test state: reads configuration
- Test UI → Input handling: receives typing
- Input handling → Typing-test runtime: mutates test
- Config and test state → Typing-test runtime: configures
- Language and test assets → Typing-test runtime: supplies words and layouts
- Typing-test runtime → Test UI: renders metrics and result
- Typing-test runtime → Typed API client: submits result
- Firebase client auth → Typed API client: provides auth
- Typed API client → API contracts: uses
- Typed API client → Express server: HTTP requests
- Express server → Routes and middleware: assembles
- Routes and middleware → Result controller: result endpoints
- Routes and middleware → User controller: account endpoints
- API contracts → Routes and middleware: implemented by adapter
- Validation schemas → Result controller: validates payloads
- Result controller → Anti-cheat: verifies submission
- Anti-cheat → Persistence DAL: accepts verified result
- Result controller → Persistence DAL: stores result
- User controller → Persistence DAL: accounts and connections
- Persistence DAL → MongoDB: durable records
- Persistence DAL → Redis: leaderboards and rate data
- Workers and scheduled jobs → Redis: consumes queues and ranks
- Workers and scheduled jobs → MongoDB: refreshes data
- Container stack → Browser bootstrap: serves frontend build
- Container stack → Express server: runs backend