Evospin / dropbet — Documentation Portal¶

Version: v1.0 (current). Older releases are archived under versions/. Style guide: STYLE.md — terminology, voice, customer-safe vs internal markers.

What is Evospin?¶

Evospin is a turnkey, source-shipped iGaming platform — backend monorepo + player site + admin SPA. The player site is branded dropbet; the codebase is shared across staging, production, and any white-labeled customer deployments.

Full elevator pitch: business/value-proposition.md. Stack inventory: engineering/stack.md.

This portal documents the system as it runs today: the architecture, the API surface, the operational runbooks, and the commercial / delivery context that surrounds them.

Three reading tracks¶

Pick the track that matches your role. Each track has its own README that sequences the docs in the recommended reading order.

Track	Audience	Start here
Business	Sales, leadership, prospect	`business/README.md`
Delivery	PM, integration partner, customer team	`delivery/README.md`
Engineering	Developers, SRE, on-call	`engineering/README.md`

The three tracks are role-shaped views over the same underlying material; they link into the cross-cutting directories rather than duplicating content. If you're not sure which track applies, jump to Reading order recommendations below — those routes are organized by goal rather than role.

Cross-cutting docs¶

These are referenced from every track. Bookmark them.

API reference (api-reference/) — single source of truth for the REST + websocket surface, generated from the live OpenAPI specs (api on 4000, bo on 4003) plus the websocket event source tree. Entry point: api-reference/index.md.
Architecture (architecture/) — service map, OTel tracing flow, and sequence diagrams for sign-in and bet-place. The conceptual long-form companion is architecture.md.
Performance — methodology and k6 profiles in performance-testing.md; latest run results in performance-test-report.md.
Security (security/) — split into a customer-safe layer (categories, severities, mitigation status) and an internal layer (full finding bodies). Consolidated register at security-register.md.
Handover kit (handover/) — onboarding day-1 / day-7 / day-14, incident runbook, support model, escalation matrix.
Onboarding review / known onboarding gaps (audits/ONBOARDING-REVIEW.md) — current list of onboarding/documentation mismatches and improvement proposals to burn down.
Service catalog (SERVICE-CATALOG.md) — operator-facing CMDB of every service (NestJS apps, frontends, datastores, messaging, observability, third-parties) with owner / SLA / dashboard / runbook / API per entry, plus a find-by-symptom triage table.
E2E trace demo (e2e-trace-demo.md) — runnable walkthrough that produces a real Jaeger trace from a single bet, end to end.
Glossary (glossary.md) — every domain term with a file:line citation back to the source tree (143 entries).
FAQ (FAQ.md) — quick answers across all four tracks (business, delivery, engineering, handover) plus cross-cutting source-of-truth pointers.
Environment variables (env-reference.md) — every env var across the three repos, plus a local-vs-prod diff.
Observability (observability.md) — OTel collector, Grafana, Jaeger, Loki, spanmetrics, validation curls.
API tooling (api/) — Postman collection generated from OpenAPI, plus the API changelog.
Admin panel (admin/) — operator's screen-by-screen reference for ebit-admin-fe (22 screen guides + index), ground-truthed against ebit-api's admin/* controllers.
Code examples (code-examples/) — runnable TypeScript samples partners can copy-paste: auth, webhooks, partner-integration REST clients, OTel emit/correlate, websocket client, k6 + Playwright load-test templates. Each folder is self-contained (npm install && npm run tsc) and cross-linked to the relevant recipe.
API compodoc browse tree (api-compodoc/) — NestJS module / DI / decorator browser auto-generated from ebit-api/'s TypeScript source. ~1,870 files; 132 per-module dependency-graph SVGs. Open api-compodoc/index.html and click into any module.
Feature deep dives (features/) — formula-first walkthroughs of the eight high-stakes business features (rakeback, VIP, leaderboard, promos, KYC, affiliate, bet settlement, wallet). Each doc states the math, a worked example, code citations, and admin overrides.
Versions (versions/) — release model + changelog. Tagged releases live in git, not as snapshot directories.
Doc CI (ci/) — link checker, {{TBD}} scanner, terminology lint rules.

Versions¶

This portal is versioned via annotated git tags (v1.0, v1.1, …). The working copy at docs/ (this directory) tracks master; tagged releases are immutable history. The release log lives in versions/changelog.md; the model and release process in versions/README.md.

When you cite a doc in an external ticket or email, link via the tag path on GitHub so the URL stays stable across edits to master:

https://github.com/evo-spin/ebit-docs/blob/v1.0/business/value-proposition.md

Reading order recommendations¶

Goal-oriented routes through the portal. Each route is 3–4 docs that answer the goal end-to-end.

Your goal	Reading order
I'm evaluating Evospin for a partnership	`business/value-proposition.md` → `architecture/service-map.md` → `e2e-trace-demo.md`
I'm onboarding as a new developer	`onboarding/day-one.md` → `onboarding/anatomy-of-a-bet.md` → `onboarding/curriculum.md` → `handover/oncall-readiness.md`
I'm investigating a production incident	`handover/oncall-runbook.md` → `runbooks/` → `observability.md`
I want to integrate with the API	`api-reference/auth-flow.md` → `api-reference/api.md` → `api/` (Postman collection)
I want to browse the Nest architecture	`api-compodoc/index.html` → click into any module's `dependencies.svg` → `architecture/service-map.md` for the bigger picture
I'm planning a launch / go-live	`delivery/README.md` → `performance-test-report.md` → `handover/`
I'm doing a security review	`security/` → `security-register.md` → `adr/`
I want to extend the system	`recipes/` → `architecture/` → relevant flow doc in `flows/`

If your goal isn't listed, scan the cross-cutting list above — every entry is annotated with the audience that benefits most from it.

Quick start (for engineers)¶

The fastest path from zero to a running stack:

cd <REPO_ROOT>/ebit-api
npm run dockers:infra              # Postgres + Redis (×2) + RabbitMQ
npm i && npm run db:migrate:dev && npm run db:seed
npm run start:dev                  # api on :4000, Swagger at /swagger
npm run start:dev:rt               # rt on :4001, namespace /events

For the player UI:

cd <REPO_ROOT>/ebit-fe
pnpm install && pnpm dev           # Next.js on :3000

Full setup, lint discipline, and the lockfile-mixing trap are documented in ../CLAUDE.md (the cross-repo instruction file at the workspace root). Detailed onboarding is in onboarding/day-one.md.

Search hint¶

When in doubt, grep. The portal is plain Markdown; every term has at most one canonical definition (in glossary.md) and every code reference uses file_path:line_number so symbols are greppable across the doc set and the source tree.

# from repo root
grep -r "BullMQ" docs/
grep -rn "createAndSettleBet" .

The terminology canon is enforced by Doc CI — see STYLE.md §6 for the canonical spellings.

How this portal is organized¶

The three tracks (business/, delivery/, engineering/) are role-shaped views. The cross-cutting directories (api-reference/, architecture/, flows/, runbooks/, recipes/, adr/, data-model/, onboarding/) are topic-shaped sources that the tracks link into.

Everything in the portal is customer-safe by default. Anything internal-only carries an explicit banner and lives under a */internal/ subpath — see STYLE.md §8 for the rule and the banner template. The security register is the canonical example of the split: security/ is the redacted layer; security/internal/ carries the unredacted findings.

Existing topic-shaped directories already in the portal:

flows/ — 15 narrative request traces (sign-in, bet-place, blackjack, speed-roulette, admin, …)
runbooks/ — incident-response cheat sheets keyed by symptom
recipes/ — step-by-step guides for common dev tasks (add an endpoint, model, queue, span)
adr/ — eight architecture decision records explaining non-obvious choices
data-model/ — six Prisma ERDs grouped by domain
onboarding/ — day-one runbook, two-week curriculum, anatomy-of-a-bet trace tour

This README is itself part of the versioned doc set. The latest copy lives here at docs/README.md; release snapshots are reachable via git tags (/blob/v1.0/docs/README.md).