GAME - Goals And Motivation Engine

An adaptive, programmable gamification engine

GAME turns user activity into points, coins, and behavioral incentives through programmable scoring strategies. Unlike static points APIs whose rules are frozen at design time, GAME lets a strategy react to behavior, context, and system state - so incentives can be redistributed toward under-engaged users, tasks, or regions instead of amplifying the participation inequality that fixed rules tend to reinforce.

It runs in two shapes:

• as a complete gamification backend - manage games, tasks, users, point assignment, and wallets; or

• as a scoring microservice - your system owns the application logic and calls GAME only to compute how many points an event is worth.

---

New here? Start with the path that matches your goal

This documentation follows the Diátaxis model - it separates learning-oriented tutorials, task-oriented how-to guides, understanding-oriented explanation, and dry reference. Pick your lane:

• I want to call the API in 5 minutes → Getting Started then Authentication.

• I want to integrate GAME into my product → Integrating with GAME and Strategies.

• I want to understand how it works → Overview, Architecture, The DSL Strategy Engine.

• I run it in production → Configuration Reference, Operations, Observability, Security.

• I’m contributing code → Architecture, Codebase Reference, Contributing.

Audience map

This site serves two readers at once, and every page declares which one it is written for:

Reader	You want to…	Read first
Integrator	Consume GAME from an external app as a gamification/scoring backend.	Getting Started, Authentication, Integrating with GAME, Strategies, REST API Reference
Contributor / Operator	Extend the engine, run it, or reason about its internals.	Architecture, The DSL Strategy Engine, Security, Observability, Configuration Reference, Operations

---

Overview & Concepts

• Overview
  • What is GAME?
  • The problem GAME solves
  • Two integration modes
  • Representative use cases
  • Properties that matter
  • Where to go next
• Architecture
  • The layered design
  • The life of a scoring request
  • The middleware stack (and a subtle ordering bug it fixes)
  • Dependency injection
  • Async & persistence model
  • Cross-cutting concerns
  • Where to go next
• Domain Model
  • The big picture
  • Core entities
  • The BaseModel contract
  • Identifiers: internal vs. external
  • Idempotency & concurrency
  • Where to go next

Getting Started

• Getting Started
  • Prerequisites
  • Two ways to run
  • Your first end-to-end flow
  • Running the tests
  • Troubleshooting first run
• Authentication
  • Two credentials, one decision
  • API keys
  • OAuth2 with Keycloak
  • The admin role
  • Identity bootstrapping
  • The per-request auth context
  • Quick reference

Integration Guides

• Integrating with GAME
  • The mental model
  • Managing games
  • Managing tasks
  • Awarding points
  • Reading points
  • Wallets & the economy
  • Analytics, KPIs & exports
  • A complete integration sketch
• Strategies
  • What a strategy is
  • Choosing a strategy: strategyId
  • Built-in strategies
  • Custom strategies (the DSL)
  • The custom-strategy lifecycle
  • Simulate before you ship
  • Safety limits
  • Worked example: adaptive engagement
  • Observability
• Foundations
  • GAME Definitions
  • Game Example (Use Case)
  • Strategy Creation

Engine Internals (Contributors)

• The DSL Strategy Engine
  • Why a DSL at all?
  • The pipeline
  • Execution modes
  • Limits & error taxonomy
  • Built-in strategies in code
  • Observability hooks
  • Source map
• Security
  • Threat model in one paragraph
  • Authentication
  • Authorization & data scoping
  • Abuse prevention & rate limiting
  • CORS
  • Secrets & fail-fast configuration
  • Strategy sandbox
  • Auditability
  • Hardening checklist
• Observability
  • The four signals
  • Metrics (Prometheus)
  • Logging
  • Error tracking (Sentry)
  • Strategy execution traces
  • KPIs & operational telemetry
  • What to alert on

Operations

• Configuration Reference
  • How configuration works
  • Core / application
  • Database
  • Authentication (Keycloak)
  • Security: CORS & proxies
  • Abuse prevention & rate limiting
  • Redis (optional, shared state)
  • DSL engine limits
  • DSL execution logging
  • Errors & extras
  • Pagination defaults
  • Fail-fast guards (summary)
  • Minimal production .env skeleton
• Operations
  • Deployment topology
  • Local & dev with Docker Compose
  • Production deployment
  • Kubernetes
  • Database migrations (Alembic)
  • Health, readiness & graceful shutdown
  • Scaling guidance
  • Load & performance testing
  • Runbooks

Reference

• REST API Reference
  • The live, interactive contract
  • Conventions
  • Endpoint catalog
• Codebase Reference
  • How to read it
  • Full module index
• Contributing
  • Development setup
  • Where code goes
  • Testing
  • Code style
  • Documentation
  • Submitting a change

---

At a glance

Property	Value
Stack	Python ≥ 3.12 · FastAPI/Starlette · SQLModel/SQLAlchemy 2.0 (async) · PostgreSQL · Keycloak (OIDC) · Redis (optional)
Architecture	Layered - endpoint → service → strategy engine → repository → database - wired by a dependency-injection container
Scoring	Built-in deterministic & adaptive strategies, plus a sandboxed DSL (no-code, Blockly-authored) with hard CPU/size limits
Auth	API key (X-API-Key) or OAuth2 bearer (Keycloak), with per-key scoping and rate limiting
Observability	Prometheus /metrics, structured JSON logs, Sentry, sampled DSL execution traces, KPI rollups
Reproducibility	Deterministic execution, simulation mode (isSimulated), versionable strategies - usable as an experimental research platform

---

See also

• Interactive API - every deployment serves Swagger UI at /docs and ReDoc at /redocs generated from the live OpenAPI schema.

• Source - https://github.com/fvergaracl/GAME

• License - Apache-2.0