mentor-api

Mentor API is the intelligence hub of the MathTrail platform, responsible for adapting the learning experience to each individual student. The service analyses feedback, tracks progress, and generates personalised learning recommendations.

Business Capabilities

• Feedback Analysis — Interprets student feedback on task difficulty using an LLM.
• Learning Roadmaps — Generates adaptive learning paths based on each student's current progress.
• Strategy Orchestration — Determines the optimal teaching strategy to adjust content difficulty.

System Architecture

graph LR
    User([Student UI]) -- "Auth" --> OK[Oathkeeper]
    
    subgraph MentorService [Mentor API]
        direction LR
        App["Mentor API"]
    end

    OK -- "X-User-ID" --> App

    subgraph Storage [Data Layer]
        direction TB
        PGB["PgBouncer"] --> PG[("Postgres")]
        Mig["Migration Job"] --> PG
    end

    App -- "SQL" --> PGB
    PG -- "CDC" --> RW[RisingWave CDC]

    subgraph Bus [Event Bus]
        direction TB
        AMQ{AutoMQ}
        Apr["Apicurio"]
    end

    RW -- "feedback.created" --> AMQ
    AMQ -- "progress / profile" --> App
    App -- "strategy / roadmap" --> AMQ
    App -. "schema" .-> Apr

    subgraph Support [Infra Support]
        direction TB
        Vault["Vault"] --> ESO["ESO"]
        Obs["Observability"]
    end

    ESO -- "Secrets" --> App
    App -- "Telemetry" --> Obs

    %% Styling
    classDef svc fill:#5b21b6,stroke:#7c3aed,color:#fff
    classDef authCls fill:#b45309,stroke:#f59e0b,color:#fff
    classDef dataCls fill:#1e3a5f,stroke:#3b82f6,color:#fff
    classDef cdcCls fill:#166534,stroke:#22c55e,color:#fff
    classDef eventCls fill:#1c1917,stroke:#78716c,color:#fff
    classDef secretCls fill:#7f1d1d,stroke:#ef4444,color:#fff
    classDef obsCls fill:#134e4a,stroke:#2dd4bf,color:#fff
    classDef actorCls fill:#1e1b4b,stroke:#818cf8,color:#fff

    class App svc; class OK authCls;
    class PGB,PG,Mig dataCls; class RW cdcCls; class AMQ,Apr eventCls;
    class Vault,ESO secretCls; class Obs obsCls; class User actorCls;

Loading

Development

All commands are run via just.

just deploy
just k6-load

Debug

Telepresence intercepts live cluster traffic and routes it to your local process, so you can debug against real dependencies without deploying.

just tp-intercept
go run ./cmd/server/main.go

just tp-stop

Releases

git tag -a v0.2.0 -m "Release description"
git push origin v0.2.0

GitHub Actions will build binaries, generate a Changelog, and publish a GitHub Release.