AxiomNode is an educational AI platform built as a set of microservices, developed as a Master's thesis project. A Kotlin Multiplatform mobile app and a React backoffice talk to an API gateway and Fastify BFFs, which orchestrate domain services backed by PostgreSQL and a Python AI engine (RAG + LLM) that generates quiz and word-pass content. It has CI/CD, Kubernetes (k3s) manifests and observability definitions, and each repository carries its own tests and docs; the quality gates that apply are listed below.
flowchart LR
Mobile[mobile-app] --> Gateway[api-gateway]
Backoffice[backoffice] --> Gateway
Gateway --> BffMobile[bff-mobile]
Gateway --> BffBackoffice[bff-backoffice]
BffMobile --> Users[microservice-users]
BffMobile --> Quiz[microservice-quizz]
BffMobile --> Wordpass[microservice-word-pass]
BffBackoffice --> Users
BffBackoffice --> Quiz
BffBackoffice --> Wordpass
Quiz --> AI[ai-engine]
Wordpass --> AI
BffBackoffice --> AI
| Repository | What it is |
|---|---|
| Mobile-App | Kotlin Multiplatform (Compose) client for quiz and word-pass gameplay on Android and iOS |
| Backoffice | React + TypeScript + Vite operations console: health and metrics, AI diagnostics, role-gated admin actions |
| api-gateway | Fastify edge gateway: single public entry point routing to the BFFs and the AI runtime target |
| bff-mobile | Fastify BFF with mobile-shaped gameplay APIs over the domain microservices |
| bff-backoffice | Fastify BFF and runtime control plane for the Backoffice |
| microservice-users | Player identity (Firebase auth), roles, gameplay events, stats and leaderboards |
| microservice-quizz | Quiz domain: generation via the AI engine, validation, persistence and history |
| microservice-word-pass | Word-pass domain: generation via the AI engine, validation, persistence and history |
| ai-engine | Python/FastAPI AI engine: RAG ingestion, local/split llama inference, structured game generation |
| contracts-and-schemas | Versioned OpenAPI specs, JSON Schemas and event contracts |
| shared-sdk-client | Shared SDK workspace: TypeScript client generated from the contracts, plus Python and Kotlin scaffolds |
| platform-infra | Kubernetes (k3s/Kustomize) manifests, environment overlays, image builds and the (historical) staging rollout |
| observability-platform | Dashboards, alert rules and base stack definitions for metrics, logs and traces |
| docs | Architecture (C4 views, ADRs), capability dossiers, guides and runbooks |
- Mobile: Kotlin Multiplatform, Compose, Firebase authentication
- Web: React, TypeScript, Vite
- Backend: Fastify, TypeScript, Zod, Prisma, PostgreSQL
- AI: Python, FastAPI, RAG, local or split llama-compatible inference, structured generation
- Delivery: GitHub Actions, GHCR, Docker, Kubernetes (k3s) manifests with Kustomize
- Observability: metrics, logs and traces with shared dashboards and alert rules
- Coverage gates enforced in CI: Vitest thresholds of 90 % for lines, statements and functions in Backoffice, api-gateway, bff-backoffice, bff-mobile, microservice-quizz, microservice-users and microservice-word-pass (branch thresholds are 90 %, except 85 % in Backoffice and 88 % in bff-backoffice), and a 90 %
fail_underwith branch coverage on the Python ai-engine. The other repositories have no coverage gate - CodeQL and Trivy scans (CodeQL analysis plus a Trivy filesystem scan, run on push, pull request and a weekly schedule) in Backoffice, ai-engine, api-gateway, bff-backoffice, bff-mobile, microservice-quizz, microservice-users and microservice-word-pass. Mobile-App, contracts-and-schemas, docs, observability-platform, platform-infra and shared-sdk-client do not run them
- Contract-first: OpenAPI and JSON Schemas live in one repository and the SDK client is generated from them
- Rollout: during the thesis, a green push to
mainbuilt images and rolled out staging with smoke checks on k3s; production was a controlled manual promotion. That k3s host is gone,deploy.yamlis now manual-only, and the stack runs locally with Docker Compose (see RUN-LOCALLY.md)
No private configuration needed: clone the services and start the demo stack with Docker Compose (local Postgres, Firebase in dev mode, AI generation optional). Step-by-step guide: platform-infra/docs/RUN-LOCALLY.md.
Start with docs. Each repository's own README covers local setup, endpoints and validation commands.
All repositories are distributed under the Apache License 2.0, except this .github repository, which is MIT. Each repository's LICENSE file is authoritative.