IVR Business Logic

Scope

dmind-ivr-backend is the HTTP adapter between the telephone/IVR experience and the DMIND AI controller. It records call progress, maintains a short-lived interview session, forwards audio answers, stores the final assessment, and supports recent-severe and feedback checks.

Every business route requires the shared API access key in the token header. POST /timestamp requires a non-empty session_id and can create its Redis mapping; the other business routes require the session_id to resolve in Redis. The unauthenticated health endpoint is GET /, which returns HTTP 200 with JSON string "Hello World!".

Call lifecycle

Endpoint behavior

Endpoint	State transition
POST /timestamp	Creates an interview and Redis session for a new session_id, or appends a call step to an existing interview. It refreshes the session TTL and enforces the configured per-session timestamp limit.
POST /interview/start	Creates an audio prediction in the AI controller, stores the returned prediction_id in Mongo, and adds it to the Redis session. Repeating the call replaces the active prediction ID.
POST /interview/answer	Validates that the uploaded file is a non-empty .mp3, maps the IVR question ID to the AI question ID, and forwards the file to /submit-answer. The last question records a submission timestamp in Redis.
POST /interview/answer-suicidal	Records the caller's fallback self-rating. Choice 1 maps to LOW; choice 2 maps to SEVERE. The source is stored as FALLBACK.
GET /interview/result	Returns a previously stored result when available. Otherwise it polls the AI controller and, once finished, stores the AI result, severity, and source AI_SERVICE, replacing any earlier top-level fallback severity/source.
GET /interview/severe	Loads the last day of interviews by phone, newest first. Encountering any PICK_UP timestamp immediately returns no recent-severe follow-up; otherwise any severe interview makes recent_severe true.
POST /feedback	Stores the configured feedback choice on the current interview.

State and timing rules

• The default Redis session TTL is 120 minutes; every timestamp and interview start refreshes it.
• The configured timestamp limit defaults to 2,000 /timestamp requests per session. A value of zero disables the limit.
• Mongo is authoritative for completed interview and assessment data. Redis is required for an active request but is not the durable result store.
• The final-question timestamp is used to emit AI_DURATION when a finished AI result is first persisted.
• RESPONSE_COUNT metrics are emitted for /timestamp and /interview/answer, dimensioned by route and status code; answers also include QUESTION_ID.

Failure semantics

• An unknown/expired session_id blocks every session-protected route even if its Mongo interview still exists.
• A non-.mp3 or zero-byte answer is rejected before the AI call.
• AI transport/status failures are translated to the IVR service's internal-AI response; they do not create a fallback result automatically.
• A finished result is read from Mongo on later polls, so the AI controller is not called again for that interview.
• Timestamp rate limiting increments and persists the counter even for an over-limit call, then returns the configured rate-limit error.

AI contract

Production uses AI service bundle 1_2_0 and the same public controller interface as Prescreening:

1. POST /prediction with interview_id, configured AI version, interview_source (IVR in production), and type AUDIO.
2. POST /submit-answer as multipart data with prediction_id, mapped question_id, type AUDIO, and the MP3 file.
3. GET /result?prediction_id=... until the controller reports FINISH.

Release v1.1.1 uses this IVR-to-AI question mapping:

IVR question	AI question	IVR question	AI question
QUESTION_01	qs-01-02	QUESTION_06	qs-07-01
QUESTION_02	qs-01-03	QUESTION_07	qs-07-03
QUESTION_03	qs-03	QUESTION_08	qs-01-05
QUESTION_04	qs-03-04-01	QUESTION_09	qs-08-02
QUESTION_05	qs-03-04-02

The stored result includes depression level, two-question flags, suicidal score/level/detail, and chief-complaint terms. Its top-level source is AI_SERVICE or FALLBACK.