MathTrail

AI platform that helps students learn to solve math olympiad problems through personalized adaptive learning.

See project overview for architecture details. See workspace setup for getting started.

Local Machine Setup

Provisions the local machine: installs Docker and configures it to store images on the secondary disk.

1. Install just

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/.local/bin

Make sure ~/.local/bin is in your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

2. Run provisioning

just provision

This will:

1. Check that Ansible >= 2.17.0 is installed (installs via pip3 if not)
2. Pull Ansible roles from infra and infra-local-k3s via ansible-galaxy
3. Run the playbook — installs Docker and sets image storage to /media/data

To use a different disk, edit ansible/group_vars/all.yml before running.

Project Structure

Group	Repository	Description
Foundation	mathtrail	Workspace hub: Skaffold orchestrator, docs, diagrams
	mathtrail-service-template	Golden template for new microservices (infra/, CI/CD)
Business	mathtrail-identity	Authentication & authorization (Ory Kratos/Hydra/Keto/Oathkeeper)
	mathtrail-profile	Student knowledge graph, progress history, XP tracking
	mathtrail-mentor	AI strategist — learning strategy, skill gap analysis
	mathtrail-task	Task orchestrator — turns Mentor parameters into problems
AI & Engine	mathtrail-llm-taskgen	LLM connector for math problem generation
	mathtrail-solution-validator	Solution checking engine (symbolic math, logic)
Interfaces	mathtrail-ui-web	Student web app (React/Vite/Tailwind/shadcn)
	mathtrail-ui-chatgpt	ChatGPT plugin / custom GPTs integration
Infrastructure	mathtrail-infra	Global manifests: Vault, ESO, Telepresence
	mathtrail-charts	Centralized Helm chart repository (GitHub Pages)
	mathtrail-gitops	Centralized GitOps: ArgoCD App-of-Apps, releases, environments
	mathtrail-infra-local	Local dev infra: PostgreSQL, Redis, Kafka
	mathtrail-infra-local-k3s	K3d cluster creation and kubeconfig
	mathtrail-infra-observability	Grafana LGTM, OpenTelemetry, Pyroscope
	mathtrail-infra-testing	E2E & load testing (k6 operator)

Architecture Documentation

Diagram	Description
Microservices Interaction	Service communication map, HTTP invocation & Kafka pub/sub topics, secrets flow
Identity & Auth Flow	Ory stack architecture, registration/login/authorization sequence diagrams
GitOps & Deployment	Code-to-runtime pipeline, App-of-Apps pattern, three deployment scenarios
Observability Stack	Telemetry pipeline, OTel Collector config, Grafana LGTM + Pyroscope