How jpisop007/jeevo works
1. Overall shape
- This repo is a Python backend for the Jeevo WhatsApp healthcare platform.
- The architecture is a FastAPI application with a clear split between API entrypoints, business logic, service integrations, and persistence layers.
2. Primary runtime boundary
- app/main.py is the application bootstrap. It wires configuration, database startup, Redis connectivity, and the HTTP server.
- The app is designed to run behind Uvicorn, typically containerized via the included Dockerfile and docker-compose.yml.
3. HTTP/API layer
- app/routes/webhook.py exposes the public WhatsApp-facing endpoints:
- GET /webhook for Meta/WhatsApp verification
- POST /webhook for inbound WhatsApp events
- The same FastAPI app also serves operational endpoints like / and /health for readiness/monitoring.
4. Inbound message flow
- WhatsApp Cloud API posts message events to the webhook.
- The backend parses the event, identifies or creates the user, persists the message/conversation, updates session context, and sends a response back through WhatsApp.
- The README describes the current response behavior as simple echo/welcome logic, so the app is already wired for conversational handling even before richer AI behavior is fully used.
5. Service layer
- app/services/whatsapp_service.py is the integration boundary to Meta’s WhatsApp API using httpx.
- app/services/cache_service.py wraps Redis-backed session/context caching and short-lived data storage.
- This layer isolates third-party network calls and cache access from the web routes and business logic.
6. Persistence layer
- app/database/base.py and app/database/models.py define the PostgreSQL/SQLAlchemy data layer.
- app/database/repositories.py is the repository boundary for database access, keeping SQLAlchemy usage out of route handlers.
- The schema includes six tables: users, conversations, reminders, local_risk_levels, health_alerts, and sessions, plus enums for language, reminder type, and risk level.
7. State and caching
- Redis is used for session management and fast access to recent conversation state.
- The repo’s README indicates short TTL-based caching for conversation context and user/session data, which reduces repeated database reads during WhatsApp interactions.
8. Domain/logic layer
- app/logic/language_manager.py handles language preference and likely response localization.
- app/logic/multimodal_router.py suggests routing between text, audio, image, and other message modalities.
- This is the main business-logic boundary between raw WhatsApp payloads and the rest of the system.
9. AI integration boundary
- app/ai/llm.py, whisper_stt.py, elevenlabs_tts.py, and vision.py are integration modules for language model, speech-to-text, text-to-speech, and vision capabilities.
- These modules indicate the backend is structured to support multimodal health assistance, even if the initial runtime behavior is still lightweight.
10. Configuration and environment
- app/config/settings.py centralizes environment-driven configuration.
- The README shows dependencies on WhatsApp credentials, PostgreSQL, Redis, and server settings via .env, making external infrastructure part of the deployment contract rather than hardcoded logic.
11. Data model and message objects
- app/models/message.py contains Pydantic models for request/response validation and internal message structures.
- This acts as the contract between incoming webhook payloads, internal processing, and outgoing responses.
12. Utilities and helpers
- app/utils/helpers.py holds shared helper functions used across the app.
- This is a small cross-cutting layer for formatting, parsing, or other reusable operations that don’t belong in the core domain objects.
13. External systems
- The backend depends on three major external systems:
- Meta WhatsApp Cloud API for inbound/outbound messaging
- PostgreSQL 15 for durable health/user/conversation data
- Redis 7 for session and cache storage
- The AI modules also imply optional external AI providers or model services, though those integrations are encapsulated.
14. Support files and validation
- demo_bot.py, test_bot.py, and test_simple.py provide local testing/demo entrypoints.
- The repo is therefore set up not just as an API service, but as a small platform backend with operational, persistence, and integration boundaries already defined.
Main entry points: multimodal_router.py Router · main.py App start · webhook.py Webhook · repositories.py Repositories
Components 18
Runtime
Application bootstrap and deployment entrypoints
- App start · Starts the service, wires configuration, database, Redis, and HTTP server setup.
jeevo-backend/app/main.py - Settings · Environment-driven configuration for credentials, infrastructure, and runtime settings.
jeevo-backend/app/config/settings.py - Compose · Container orchestration for local or deployed multi-service execution.
jeevo-backend/docker-compose.yml
API
HTTP routes and request/response models
- Webhook · Public WhatsApp webhook plus health and verification endpoints.
jeevo-backend/app/routes/webhook.py - Message models · Request, response, and internal message structures used across the app.
jeevo-backend/app/models/message.py
Domain
Core conversation logic and orchestration
Integrations
External service adapters for messaging, cache, and AI
- WhatsApp API · Outbound integration to Meta WhatsApp Cloud API over HTTP.
jeevo-backend/app/services/whatsapp_service.py - Cache · Redis-backed cache for session state and recent conversation context.
jeevo-backend/app/services/cache_service.py - LLM · Language model integration boundary for conversational assistance.
jeevo-backend/app/ai/llm.py - Speech-to-text · Audio transcription integration for voice message handling.
jeevo-backend/app/ai/whisper_stt.py - Text-to-speech · Speech synthesis integration for spoken responses.
jeevo-backend/app/ai/elevenlabs_tts.py - Vision · Image understanding integration for multimodal inputs.
jeevo-backend/app/ai/vision.py
Data
Database schema and persistence access
- DB setup · Database engine and session setup for PostgreSQL access.
jeevo-backend/app/database/base.py - Schema · Persistent entities for users, conversations, reminders, alerts, and sessions.
jeevo-backend/app/database/models.py - Repositories · Repository boundary that encapsulates SQLAlchemy persistence operations.
jeevo-backend/app/database/repositories.py
Connections 20
- App start → Settings: loads · Bootstraps runtime configuration from the environment.
- App start → DB setup: initializes · Creates database connectivity during startup.
- App start → Cache: connects · Verifies or prepares Redis-backed state access.
- App start → Webhook: serves · Registers the HTTP application and routes.
- Webhook → Message models: validates · Parses inbound webhook payloads into typed message objects.
- Webhook → Router: dispatches · Sends inbound events into the main conversation router.
- Router → Language: uses · Applies language preference and localization behavior.
- Router → WhatsApp API: replies via · Sends responses back through WhatsApp.
- Router → Cache: reads/writes · Updates session context and short-lived conversation state.
- Router → Repositories: persists · Stores users, conversations, reminders, and related records.
- Router → LLM: can invoke · Routes conversational requests to language model services when needed.
- Router → Speech-to-text: can invoke · Handles voice inputs through transcription.
- Router → Vision: can invoke · Handles image inputs through vision processing.
- Router → Text-to-speech: can invoke · Generates audio responses when spoken output is required.
- Repositories → Schema: maps to · Implements persistence over the SQLAlchemy domain schema.
- Repositories → DB setup: uses · Relies on the database session and engine setup.
- Cache → Settings: reads config · Uses Redis connection details and cache settings.
- WhatsApp API → Settings: reads config · Uses API credentials and delivery settings.
- Demo bot → WhatsApp API: exercises · Uses the messaging client for local testing or demos.
- Compose → App start: runs · Containerizes the backend application runtime.