# monkeytypegame/monkeytype architecture

> Architecture diagram of the GitHub repository monkeytypegame/monkeytype, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/monkeytypegame/monkeytype
- Repository: https://github.com/monkeytypegame/monkeytype
- Video tour (about a minute): https://gitdiagram.com/monkeytypegame/monkeytype/video

## Overview

#### 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: [`frontend/src/ts/test/test-logic.ts`](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/test/test-logic.ts) (Typing-test runtime), [`backend/src/dal/result.ts`](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/dal/result.ts) (Persistence DAL), [`frontend/src/ts/components/pages/test/Monkey.tsx`](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/components/pages/test/Monkey.tsx) (Test UI), [`frontend/src/ts/ape/index.ts`](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/ape/index.ts) (Typed API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_browser["Browser bootstrap<br/>Solid entry<br/>[index.ts]"]
  node_navigation["Navigation controllers<br/>client routing"]
  node_test_ui["Test UI<br/>Solid components<br/>[Monkey.tsx]"]
  node_test_runtime["Typing-test runtime<br/>client test logic<br/>[test-logic.ts]"]
  node_input["Input handling<br/>input boundary<br/>[input-element.ts]"]
  node_client_state["Config and test state<br/>client stores<br/>[store.ts]"]
  node_static_assets["Language and test assets<br/>static JSON<br/>[english.json]"]
  node_api_client["Typed API client<br/>ts-rest client<br/>[index.ts]"]
  node_firebase_client["Firebase client auth<br/>auth integration<br/>[firebase.ts]"]
end

subgraph group_shared["Shared contracts"]
  node_contracts["API contracts<br/>shared contracts<br/>[index.ts]"]
  node_schemas["Validation schemas<br/>shared Zod schemas<br/>[results.ts]"]
end

subgraph group_backend["Backend API"]
  node_server["Express server<br/>HTTP process<br/>[server.ts]"]
  node_routes["Routes and middleware<br/>request pipeline<br/>[index.ts]"]
  node_result_controller["Result controller<br/>result API<br/>[result.ts]"]
  node_user_controller["User controller<br/>account API<br/>[user.ts]"]
  node_anticheat["Anti-cheat<br/>result verification<br/>[index.ts]"]
end

subgraph group_async["Data and async"]
  node_dal["Persistence DAL<br/>Mongo/Redis access<br/>[result.ts]"]
  node_mongodb[("MongoDB<br/>durable store<br/>[db.ts]")]
  node_redis[("Redis<br/>cache, ranks, queues<br/>[redis.ts]")]
  node_workers_jobs["Workers and scheduled jobs<br/>background processing<br/>[email-worker.ts]"]
end

subgraph group_deploy["Deployment"]
  node_containers{{"Container stack<br/>Docker deployment<br/>[docker-compose.yml]"}}
end

node_browser -->|"selects pages"| node_navigation
node_browser -->|"mounts"| node_test_ui
node_test_ui -->|"reads configuration"| node_client_state
node_test_ui -->|"receives typing"| node_input
node_input -->|"mutates test"| node_test_runtime
node_client_state -->|"configures"| node_test_runtime
node_static_assets -->|"supplies words and layouts"| node_test_runtime
node_test_runtime -->|"renders metrics and result"| node_test_ui
node_test_runtime -->|"submits result"| node_api_client
node_firebase_client -->|"provides auth"| node_api_client
node_api_client -->|"uses"| node_contracts
node_api_client -->|"HTTP requests"| node_server
node_server -->|"assembles"| node_routes
node_routes -->|"result endpoints"| node_result_controller
node_routes -->|"account endpoints"| node_user_controller
node_contracts -->|"implemented by adapter"| node_routes
node_schemas -->|"validates payloads"| node_result_controller
node_result_controller -->|"verifies submission"| node_anticheat
node_anticheat -->|"accepts verified result"| node_dal
node_result_controller -->|"stores result"| node_dal
node_user_controller -->|"accounts and connections"| node_dal
node_dal -->|"durable records"| node_mongodb
node_dal -->|"leaderboards and rate data"| node_redis
node_workers_jobs -->|"consumes queues and ranks"| node_redis
node_workers_jobs -->|"refreshes data"| node_mongodb
node_containers -.->|"serves frontend build"| node_browser
node_containers -.->|"runs backend"| node_server

click node_browser "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/index.ts"
click node_navigation "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/controllers/route-controller.ts"
click node_test_ui "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/components/pages/test/Monkey.tsx"
click node_test_runtime "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/test/test-logic.ts"
click node_input "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/input/input-element.ts"
click node_client_state "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/config/store.ts"
click node_static_assets "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/static/languages/english.json"
click node_api_client "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/ape/index.ts"
click node_firebase_client "https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/firebase.ts"
click node_contracts "https://github.com/monkeytypegame/monkeytype/blob/master/packages/contracts/src/index.ts"
click node_schemas "https://github.com/monkeytypegame/monkeytype/blob/master/packages/schemas/src/results.ts"
click node_server "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/server.ts"
click node_routes "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/api/routes/index.ts"
click node_result_controller "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/api/controllers/result.ts"
click node_user_controller "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/api/controllers/user.ts"
click node_anticheat "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/anticheat/index.ts"
click node_dal "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/dal/result.ts"
click node_mongodb "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/init/db.ts"
click node_redis "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/init/redis.ts"
click node_workers_jobs "https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/workers/email-worker.ts"
click node_containers "https://github.com/monkeytypegame/monkeytype/blob/master/docker/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_browser,node_navigation,node_test_ui,node_test_runtime,node_input,node_client_state,node_static_assets,node_api_client,node_firebase_client toneBlue
class node_contracts,node_schemas toneAmber
class node_server,node_routes,node_result_controller,node_user_controller,node_anticheat toneMint
class node_dal,node_mongodb,node_redis,node_workers_jobs toneRose
class node_containers toneIndigo
```

## Components

### Frontend

Solid/Vite browser application.

- [Browser bootstrap](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/index.ts): Solid entry · `frontend/src/ts/index.ts`
- [Navigation controllers](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/controllers/route-controller.ts): client routing · `frontend/src/ts/controllers/route-controller.ts`
- [Test UI](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/components/pages/test/Monkey.tsx): Solid components · `frontend/src/ts/components/pages/test/Monkey.tsx`
- [Typing-test runtime](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/test/test-logic.ts): client test logic · Computes live typing metrics and final result locally. · `frontend/src/ts/test/test-logic.ts`
- [Input handling](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/input/input-element.ts): input boundary · `frontend/src/ts/input/input-element.ts`
- [Config and test state](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/config/store.ts): client stores · Persists local configuration and holds active test state. · `frontend/src/ts/config/store.ts`
- [Language and test assets](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/static/languages/english.json): static JSON · `frontend/static/languages/english.json`
- [Typed API client](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/ape/index.ts): ts-rest client · `frontend/src/ts/ape/index.ts`
- [Firebase client auth](https://github.com/monkeytypegame/monkeytype/blob/master/frontend/src/ts/firebase.ts): auth integration · `frontend/src/ts/firebase.ts`

### Shared contracts

Typed API and validation boundary.

- [API contracts](https://github.com/monkeytypegame/monkeytype/blob/master/packages/contracts/src/index.ts): shared contracts · Single typed client-server API definition. · `packages/contracts/src/index.ts`
- [Validation schemas](https://github.com/monkeytypegame/monkeytype/blob/master/packages/schemas/src/results.ts): shared Zod schemas · `packages/schemas/src/results.ts`

### Backend API

Express request pipeline and domain operations.

- [Express server](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/server.ts): HTTP process · `backend/src/server.ts`
- [Routes and middleware](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/api/routes/index.ts): request pipeline · Applies context, auth, rate limits, and errors before controllers. · `backend/src/api/routes/index.ts`
- [Result controller](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/api/controllers/result.ts): result API · `backend/src/api/controllers/result.ts`
- [User controller](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/api/controllers/user.ts): account API · `backend/src/api/controllers/user.ts`
- [Anti-cheat](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/anticheat/index.ts): result verification · `backend/src/anticheat/index.ts`

### Data and async

Persistence, Redis processing, and background work.

- [Persistence DAL](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/dal/result.ts): Mongo/Redis access · Domain modules isolate application queries and storage behavior. · `backend/src/dal/result.ts`
- [MongoDB](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/init/db.ts): durable store · `backend/src/init/db.ts`
- [Redis](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/init/redis.ts): cache, ranks, queues · Leaderboard scripts perform result and rank operations. · `backend/src/init/redis.ts`
- [Workers and scheduled jobs](https://github.com/monkeytypegame/monkeytype/blob/master/backend/src/workers/email-worker.ts): background processing · Processes queued email and refreshes leaderboard data. · `backend/src/workers/email-worker.ts`

### Deployment

Separate frontend and backend container stack.

- [Container stack](https://github.com/monkeytypegame/monkeytype/blob/master/docker/docker-compose.yml): Docker deployment · Frontend and Node backend are independently containerized. · `docker/docker-compose.yml`

## Connections

- 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
