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 Platform]
        direction LR
        App["Mentor API"]
        Sidecar["Dapr Sidecar"]
        App <--> Sidecar
    end

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

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

    Sidecar -- "SQL" --> PGB
    PG -- "CDC" --> Deb[Debezium]
    
    subgraph Bus [Event Bus]
        Kfk{Kafka}
    end

    Deb -- "feedback.created" --> Kfk
    Kfk -- "progress / profile" --> App
    App -- "strategy / roadmap" --> Kfk

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

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

    %% Styling
    classDef svc fill:#5b21b6,stroke:#7c3aed,color:#fff
    classDef dapr fill:#0369a1,stroke:#38bdf8,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 Sidecar dapr; class OK authCls;
    class PGB,PG,Mig dataCls; class Deb cdcCls; class Kfk 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   # deploy → connect to cluster → start intercept on port 8080
go run ./cmd/server/main.go

just tp-stop        # leave intercept and disconnect

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.