Skip to content

README.md

Latest commit

 

History

History
165 lines (128 loc) · 5.73 KB

README.md

File metadata and controls

165 lines (128 loc) · 5.73 KB
Raw

TypeThock

TypeThock is a quiet, keyboard-first typing practice application. The typing loop runs entirely in the browser; an optional account preserves results across devices through a Spring Boot API.

The product includes word and timed tests, English and Spanish word lists, 1,030 attributed public-domain or TypeThock-original quotations, tab-private custom text, strict error behavior, punctuation and number modifiers, and an original code-learning corpus with 32 algorithm concepts placed in 16 mnemonic contexts across C++, Java, Python 3, C, C#, JavaScript, TypeScript, and Go. That produces 4,096 contextual typing drills, not 4,096 distinct algorithms. It also includes deterministic prompts, restart shortcuts, detailed scoring, three original themes, guest history, account history, JSON export, and password-confirmed account deletion. It does not send a request for each keystroke.

Stack

  • React 19, strict TypeScript, Vite, and React Router 8
  • Spring Boot 4.1 on Java 21
  • PostgreSQL 18 with Flyway migrations
  • Nginx as the same-origin static server and API proxy
  • Vitest, Testing Library, Playwright, JUnit, MockMvc, and Testcontainers
  • Docker Compose for the complete deployment topology

Quick start

Requirements: Docker Desktop with Compose.

  1. Copy .env.example to .env.

  2. Keep the local profile values for local HTTP only. Change all three example database passwords if the data will matter.

  3. Start the stack:

    docker compose up --build --wait

  4. Open http://127.0.0.1:8080.

  5. Stop it with docker compose down. Add --volumes only when you intentionally want to erase the local database.

The bootstrap administrator, non-superuser Flyway owner, and DML-only application role are separate. A one-shot permission gate revokes runtime access to Flyway history before the backend starts.

Development

Use Node 22.22 or newer (CI uses Node 24.18), Java 21, and Docker. The repository includes Maven wrappers.

Start PostgreSQL/backend with Compose, then run the frontend dev server:

cd frontend
npm ci
npm run dev

Vite listens only on 127.0.0.1:5173 and proxies /api to the Compose web endpoint on port 8080. Guest typing still works if the API is unavailable.

Verification

Backend (requires a running Docker engine for PostgreSQL Testcontainers):

cd backend
./mvnw verify

On Windows PowerShell use .\mvnw.cmd verify.

Frontend:

cd frontend
npm ci
npm audit --audit-level=high
npm run typecheck
npm run lint
npm run test:run
npm run test:code-corpus
npm run build
npx playwright install
npm run test:e2e

With the production Compose stack running, the browser performance/security smoke and Monkeytype epoch fingerprint are reproducible with:

PERF_BASE_URL=http://127.0.0.1:8080 npm run test:perf
npm run audit:monkeytype-epoch

test:perf uses real Playwright browser input, records before-input-to-frame timing, long tasks, layout shifts, network activity, CSP violations, runtime errors, and overflow. It is a bounded smoke measurement, not a laboratory benchmark.

Account-lifecycle E2E runs against the full stack:

E2E_BASE_URL=http://127.0.0.1:8080 E2E_ACCOUNT=true \
  npx playwright test --project=chromium --grep "account result"

PowerShell:

$env:E2E_BASE_URL = "http://127.0.0.1:8080"
$env:E2E_ACCOUNT = "true"
npx playwright test --project=chromium --grep "account result"

The GitHub Actions workflow repeats the primary gates from clean dependency installs. A workflow file existing locally is not evidence that it has run on GitHub.

Repository map

backend/             Spring API, security, persistence, migrations, tests
frontend/            React app, typing engine, UI, unit and browser tests
ops/nginx/           same-origin proxy and browser security headers
ops/postgres/init/   bootstrap, migration-owner, and runtime-role grants
docs/product/        release scope and normative typing behavior
docs/architecture/   component, data, and HTTP contracts
docs/design/         visual, responsive, motion, and accessibility direction
docs/security/       implementation-grounded threat model
docs/operations/     deployment, migration, backup, and recovery runbook
docs/reviews/        specialist findings and root-agent evaluations
docs/testing/        parity catalog, generated status, and campaign evidence
compose.yaml         production-shaped local topology

Production boundary

Compose exposes only Nginx. A real deployment must put an HTTPS ingress in front, use unique high-entropy database passwords, keep SPRING_PROFILES_ACTIVE=prod, keep secure cookies enabled, and back up the PostgreSQL volume. Do not publish the backend or database ports.

The included application-level rate limiters are process-local. Before running multiple API replicas, add a shared limiter at the trusted ingress or in a shared store.

See deployment and maintenance, zero-cost Vercel/Render/Neon deployment, architecture, and the threat model. The original code-drill selection and copyright boundary are documented in the code-learning corpus policy. Exact local evidence and limitations are recorded in verification and the parity ledger.

Intentional release-1 limits

There is no password recovery because the product collects no email address. There are no public leaderboards or anti-cheat claims; a client can fabricate its own private result despite server-side range and formula validation. Preference sync, OAuth, MFA, a service worker, telemetry, and distributed rate limiting remain out of scope.