AxiomNode

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.

Architecture

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

Loading

Repositories

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

Tech stack

• 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

Quality bar

• 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_under with 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 main built images and rolled out staging with smoke checks on k3s; production was a controlled manual promotion. That k3s host is gone, deploy.yaml is now manual-only, and the stack runs locally with Docker Compose (see RUN-LOCALLY.md)

Run it locally

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.

Documentation

Start with docs. Each repository's own README covers local setup, endpoints and validation commands.

License

All repositories are distributed under the Apache License 2.0, except this .github repository, which is MIT. Each repository's LICENSE file is authoritative.