Skip to content
MedCase.

Architecture

One backend service, a few well-separated dependencies.

The system is a single Spring Boot service. Clients, identity, storage and AI are separate processes it talks to over HTTP or the MongoDB driver.

01

System diagram

CASE-SERVICECLIENTSIDENTITYDATA AND AIPKCEtokensWeb appsingle HTML file, React 18Mobile appExpo / React NativeKeycloakrealm clinical-aiSecurity filter chainstateless JWT validationControllers and case-access aspect~120 endpoint mappingsServicesbusiness rulesClaude client and promptssingle AI gatewayAsync push eventslisteners and receipt checkerMongoDB 8documents and GridFSOllamanomic-embed-textAnthropic Claude APItext and visionExpo Push servicenotifications

Services

Evaluation lifecycle, classrooms and assignments, practice, reveal policy, PDF import, translation, statistics and grading.

Solid lines are runtime calls. Dashed lines are identity, token validation or asynchronous work.

02

Backend structure

Code is layered inside one package: controllers and DTOs on the outside, services for business rules, documents and Spring Data repositories for persistence. Two feature packages sit beside the layers: one for AI (shared client, prompts, image helpers) and one for push notifications. Deterministic tumor-grading calculators live in their own package so they stay free of framework code.

The API exposes roughly 120 endpoint mappings across about 20 controllers, documented with OpenAPI. Errors pass through one global handler that returns a consistent body.

03

Authentication and real-time behaviour

Keycloak issues tokens. The backend is a stateless resource server: each request carries a bearer token, the filter chain validates it and maps realm roles to authorities. Web sign-in uses backend authentication endpoints that talk to Keycloak; the mobile app uses the PKCE authorization-code flow directly.

MedCase has no Server-Sent Events or WebSocket channel. Evaluations are computed inside the originating request. The one asynchronous path is push notification delivery, handled with in-process events.

04

Data

MongoDB holds twelve collections: users, cases, classrooms, assignments, submissions, evaluations, question sets, practice attempts, embedding chunks, and three for push. Images live in GridFS. A case embeds its clinical sections, translations, gradings and image analyses, so one read returns the whole case.

05

Lifecycle of an assignment

  1. 01

    Assign

    Teacher assigns a case to a classroom with a deadline. A push event is published.

  2. 02

    Submit

    Student submits answers. Duplicates and late submissions are rejected.

  3. 03

    AI evaluate

    Rubric scores per question, with retrieved case context. Status becomes AI evaluated.

  4. 04

    Teacher review

    Teacher approves or overrides rubric scores. Total is recalculated. Student is notified.

06

What is not in the system

  • No Server-Sent Events or WebSocket channel. AI calls are synchronous request/response.
  • No message broker and no separate vector database.
  • Prometheus, Grafana, Loki and OpenTelemetry are roadmap items, not deployed.
  • Keycloak runs in development mode in the sample Compose file.
  • The system is a graduation-project prototype with no published performance or scale claims.