Architecture
Request routing
The API uses an RPC-style envelope rather than REST resources. Clients POST (or GET for some public queries) a query name and a pars object.
| Endpoint | Auth | Handler | Purpose |
|---|---|---|---|
/query |
None | export const query |
Public reads, schedulers, maintenance |
/authQuery |
Cognito user JWT | export const authQuery |
Player actions and authenticated reads |
/botQuery |
Cognito M2M (bot pool) | export const botQuery |
Bots submit moves |
Source of truth for query names: route tables in api/routes/. Handler logic is implemented in lib/ modules imported by those routes.
Lambda functions
Defined in serverless.yml:
| Function | Trigger | Role |
|---|---|---|
query |
API Gateway HTTP | Public queries |
authQuery |
API Gateway HTTP + Cognito authorizer | Authenticated queries |
botQuery |
API Gateway HTTP + bot pool authorizer | Bot move submission |
connect |
WebSocket $connect |
Register connection |
disconnect |
WebSocket $disconnect |
Remove connection |
subscribe |
WebSocket subscribe route |
Authenticate and subscribe to topics |
messageHandler |
SQS ws-messages queue |
Broadcast WebSocket messages |
bot-outbound |
SQS bot-outbound queue |
HTTPS webhooks to external bots |
testBot |
API Gateway HTTP (dev only) | Reference bot implementation |
Data store
- Table:
abstract-play-{stage}(single-table design) - Region:
us-east-1 - Schema: Database schema
Dependencies
@abstractplay/gameslib— game rules,GameFactory, move validation,gameinfo@abstractplay/renderer— transitive dependency of gameslib- AWS SDK — DynamoDB, SES, SQS, Cognito Identity Provider
web-push— browser push notifications
Key modules
| Module | Responsibility |
|---|---|
api/query.ts, api/authQuery.ts, api/botQuery.ts |
HTTP Lambda entrypoints |
api/routes/ |
RPC dispatch maps to lib/* handlers |
lib/ddb.ts |
Shared DynamoDB document client |
lib/participants.ts |
Human vs bot identity, BOT records |
lib/botOutbound.ts |
Enqueue and deliver bot webhooks |
lib/botSecrets.ts |
Bot Cognito client secret rotation |
lib/botCognito.ts |
Create bot Cognito app clients |
lib/botNames.ts |
BOTNAME reservation |
lib/wsBroadcast.ts |
Queue WebSocket fan-out |
api/sockets/ |
WebSocket connect/disconnect/subscribe handlers |
api/testBot.ts |
Reference bot (dev only) |
Scheduled batch jobs (yourturn, feedback archive, records pipeline, etc.) run in the crons stack — see Crons architecture and utils/yourturn.ts (handler entry under crons/src/functions/). |
Side effects
Authenticated handlers may also call:
- SES — challenge, game end, your-turn emails
- SQS — WebSocket message queue, bot outbound queue
- Cognito — bot client create/delete/secret rotation
- CloudFront — record invalidation (some maintenance paths)
Stages
Dev and prod are separate stacks with separate Cognito pools, DynamoDB tables, and bot credentials. Dev tokens and bot credentials do not work against prod.
See Deployment for branch mapping and CI.