Backend API

Last updated: 2026-01-30

Backend API

This document provides an overview of the backend API architecture, covering its structure, configuration, routing, and key components. The API is built using the FastAPI framework.

Project Structure

The core backend logic is contained within the /api directory:

  • main.py: The main entrypoint for the FastAPI application. It initializes the app, includes routers, and configures middleware.
  • /routers: Contains the different API endpoint groups (e.g., chat.py, health.py).
  • /services: Holds the business logic that the routers delegate to (e.g., chat_service.py, feedback_service.py).
  • /agents: Contains the langgraph agent implementation which is the core of the chatbot’s brain.
  • config.py & variant_config.py: Manages application settings and deployment variants.
  • database.py: Handles database initialization and session management.
  • schemas.py: Defines the Pydantic data models used for API request and response validation.

Configuration & Secrets

Application configuration is centralized and managed through a few key files.

config.py

This file defines a settings class that holds application-wide configurations. It retrieves settings from environment variables or uses sensible defaults. Key configurations include:

  • CORS origins
  • File upload limits and types
  • LLM and RAG parameters
  • A feature flag for emotion extraction (MM_EXTRACT_EMOTION)

Secrets Management

Sensitive information like database URLs and API keys are not hardcoded. They are fetched from a secure secret manager using the utils.secret.get_secret() function. This is a critical security practice.

variant_config.py

The application can run in different “variants” (e.g., youth or adult) controlled by the CHATBOT_VARIANT environment variable. This file provides helper functions (get_chatbot_variant(), is_adult_variant()) that allow the application logic, particularly the agent, to adapt its behavior and prompts for the target audience.

Application Lifecycle

The application has custom logic for startup and shutdown, defined in api/main.py.

  • Lifespan Manager: An @asynccontextmanager named lifespan is used to run logic before the application starts serving requests and after it shuts down. On startup, it calls init_db() to ensure database tables are created.
  • Graceful Shutdown: The application uses a custom uvicorn server class, MMBackend, which overrides the shutdown method. This ensures that all active Server-Sent Event (SSE) connections are properly closed by calling sse_manager._cleanup(), preventing orphaned connections.

API Endpoints

All API endpoints are prefixed with /api/v1. The API is self-documenting; interactive documentation is available at /docs (Swagger UI) and /redoc when the application is running.

Health Check

  • GET /health: Provides a comprehensive health check that reports the status of the application, the database connection, the connection pool, and the chat service.

Chat

This is the core set of endpoints for chatbot interaction, defined in routers/chat.py.

  • POST /chat/init: Initializes a new chat session for a user, creating a unique session ID and returning the initial welcome message from the agent.
  • POST /chat: Handles a user’s message within a session. This is the main endpoint that triggers the agent to process the input and generate a response.
  • POST /chat/emotion: Used during context collection for the user to select their emotion from a predefined list.
  • POST /chat/dropdown: Used for handling user selections from a dropdown menu, typically for clarifying intent as a returning user.
  • GET /chat/{session_id}/events/listen: A Server-Sent Events (SSE) endpoint that allows the client to maintain a persistent connection and receive real-time events from the backend (e.g., for streaming agent thoughts or monster changes).
  • POST /chat/delete: Deletes a user’s conversation summary from the database.
  • POST /chat/settings/change: Allows for changing session settings like language or monster on the fly.

Audio Transcription

  • POST /audio/transcribe: Accepts an audio file, validates its type and size, and uses a transcription service to convert the speech to text.

File Management

  • POST /files/upload: Uploads one or more files.
  • GET /files/{filename}: Retrieves a previously uploaded file.
  • DELETE /files/{filename}: Deletes a file from the server.

Feedback

  • POST /feedback/{session_id}: Submits user feedback (e.g., a rating or comment) for a specific chat session.
  • GET /feedback/{session_id}: Retrieves all feedback associated with a session.

Core Services

The API routers delegate complex business logic to dedicated service classes found in /api/services.

  • ChatService: The main service that manages chat sessions, interacts with the LangGraph agent, and orchestrates the overall chat flow.
  • FeedbackService: Handles the logic for storing and retrieving user feedback from the database.
  • sse_manager: Manages all Server-Sent Event connections, allowing the agent to push real-time updates to the client.
  • AudioTranscriptionService: Provides the logic for converting audio files to text.

Data Models (Schemas)

The API uses Pydantic models defined in api/schemas.py for robust data validation and serialization. Key models include:

  • ChatRequest & ChatResponse: Define the structure for requests to and responses from the main /chat endpoint. ChatResponse is a composite object containing the new messages and the full session state.
  • ChatSessionResponse: Represents the complete state of a chat session, including all messages, collected context, and agent state flags.
  • FeedbackCreate: The model for submitting new feedback.
  • FileUploadResponse: The response model after a file is successfully uploaded.