learninglocker/xapi-service

Purpose and runtime entry points

This TypeScript/Node.js service implements an xAPI Learning Record Store API. It exposes four API domains: Statements, Agent Profiles, Activity Profiles, and State. The process is started through src/server.ts; application composition is centered in src/apps/app.ts, with domain Express apps in src/apps/statements/app.ts, src/apps/agents/app.ts, src/apps/activities/app.ts, and src/apps/states/app.ts. src/conformanceServer.ts appears to provide a separate conformance-oriented server entry point.

HTTP presentation boundary

Each domain has an Express presenter that parses xAPI HTTP requests, validates protocol headers/content types, invokes services, and maps domain errors to HTTP responses. Statements support GET/POST/PUT, multipart statement/attachment handling, About, and full-activity routes in src/apps/statements/expressPresenter/index.ts and src/apps/statements/expressPresenter/postStatements/index.ts. Profile/state endpoints use analogous presenters, e.g. src/apps/agents/expressPresenter/index.ts, src/apps/activities/expressPresenter/index.ts, and src/apps/states/expressPresenter/index.ts.

Statement ingestion pipeline

Statement writes follow a staged service pipeline: normalize incoming models, validate statements and signatures, resolve duplicate/voiding/reference rules, persist attachments and statements, derive queryable indexes, update full activities, and emit events. The orchestration is src/apps/statements/service/storeStatements/index.ts; its validation/setup stages live under src/apps/statements/service/storeStatements/preValidationSetup/ and src/apps/statements/service/storeStatements/postValidationSetup/; persistence/reference updates are under src/apps/statements/service/storeStatements/createStatements.ts and src/apps/statements/service/storeStatements/updateReferences/.

Statement query and representation flow

Read services retrieve statements, references, activities, and attachments, then apply xAPI result formatting (canonical or IDs formats) and pagination/multipart response assembly. Key boundaries are src/apps/statements/service/getStatements.ts, src/apps/statements/repo/modelsRepo/getStatements/mongo/index.ts, and src/apps/statements/service/utils/getStatementsResult.ts. The presenter owns request parameter parsing and HTTP/multipart streaming in src/apps/statements/expressPresenter/utils/getStatements/.

Profiles and state domains

Agents and activities each manage profile documents plus externally stored profile content; states manage activity-agent-registration scoped state content. Their services enforce client trust, organization/store isolation, read/write scopes, content semantics, conditional ETag updates where applicable, and patch/overwrite/delete behavior. Representative orchestration paths are src/apps/agents/service/index.ts, src/apps/activities/service/index.ts, and src/apps/states/service/index.ts. These domains share a repeated layered pattern: presenter → service → repository contracts/factories → Mongo metadata and blob storage.

Repository abstraction and infrastructure

Factories decouple domain logic from backing providers. Statements compose auth, Mongo models, attachments storage, and event repositories via src/apps/statements/repo/factory.ts and src/apps/statements/repo/facade.ts. Profile/state domains expose equivalent contracts and select implementations through paths such as src/apps/agents/repo/factory.ts, src/apps/activities/repoFactory/index.ts, and src/apps/states/repo/factory.ts.

MongoDB is the primary metadata/statement store; Redis supports statement event/queue behavior. Attachments and profile/state bodies can use local disk, AWS S3, Google Cloud Storage, or Azure Blob Storage. Statement events can use Redis or AWS SQS, as indicated by src/apps/statements/repo/eventsRepo/emitNewStatements/redis.ts, src/apps/statements/repo/eventsRepo/emitNewStatements/sqs.ts, and src/utils/connectToSQS.ts.

Deployment and operational boundaries

Runtime configuration is centralized in src/config.ts, with logging and telemetry-related modules at src/logger.ts and src/tracker.ts. Local development infrastructure is MongoDB and Redis via docker-compose.yml; production packaging is provided by Dockerfile and PM2 configuration under pm2/xapi.json.