# jpisop007/jeevo architecture

> Architecture diagram of the GitHub repository jpisop007/jeevo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jpisop007/jeevo
- Repository: https://github.com/jpisop007/jeevo

## Overview

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: [`jeevo-backend/app/logic/multimodal_router.py`](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/logic/multimodal_router.py) (Router), [`jeevo-backend/app/main.py`](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/main.py) (App start), [`jeevo-backend/app/routes/webhook.py`](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/routes/webhook.py) (Webhook), [`jeevo-backend/app/database/repositories.py`](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/database/repositories.py) (Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main["App start<br/>FastAPI bootstrap<br/>[main.py]"]
  node_settings["Settings<br/>Config<br/>[settings.py]"]
  node_compose["Compose<br/>Deployment<br/>[docker-compose.yml]"]
end

subgraph group_api["API"]
  node_webhook["Webhook<br/>HTTP routes<br/>[webhook.py]"]
  node_message_models["Message models<br/>Pydantic contracts<br/>[message.py]"]
end

subgraph group_domain["Domain"]
  node_multimodal_router{{"Router"}}
  node_language_manager{{"Language<br/>Locale logic"}}
end

subgraph group_integrations["Integrations"]
  node_whatsapp_service["WhatsApp API<br/>Messaging client"]
  node_cache_service[("Cache<br/>Redis session store<br/>[cache_service.py]")]
  node_llm["LLM<br/>AI adapter<br/>[llm.py]"]
  node_whisper_stt["Speech-to-text<br/>AI adapter<br/>[whisper_stt.py]"]
  node_elevenlabs_tts["Text-to-speech<br/>AI adapter<br/>[elevenlabs_tts.py]"]
  node_vision["Vision<br/>AI adapter<br/>[vision.py]"]
end

subgraph group_data["Data"]
  node_base[("DB setup<br/>SQLAlchemy bootstrap<br/>[base.py]")]
  node_models[("Schema<br/>SQLAlchemy models<br/>[models.py]")]
  node_repositories["Repositories<br/>DB access layer<br/>[repositories.py]"]
end

subgraph group_support["Support"]
  node_helpers["Helpers<br/>Shared utils<br/>[helpers.py]"]
  node_demo_bot["Demo bot<br/>Local demo<br/>[demo_bot.py]"]
end

node_main -->|"loads"| node_settings
node_main -->|"initializes"| node_base
node_main -->|"connects"| node_cache_service
node_main -->|"serves"| node_webhook
node_webhook -->|"validates"| node_message_models
node_webhook -->|"dispatches"| node_multimodal_router
node_multimodal_router -->|"uses"| node_language_manager
node_multimodal_router -->|"replies via"| node_whatsapp_service
node_multimodal_router -->|"reads/writes"| node_cache_service
node_multimodal_router -->|"persists"| node_repositories
node_multimodal_router -->|"can invoke"| node_llm
node_multimodal_router -->|"can invoke"| node_whisper_stt
node_multimodal_router -->|"can invoke"| node_vision
node_multimodal_router -->|"can invoke"| node_elevenlabs_tts
node_repositories -->|"maps to"| node_models
node_repositories -->|"uses"| node_base
node_cache_service -->|"reads config"| node_settings
node_whatsapp_service -->|"reads config"| node_settings
node_demo_bot -.->|"exercises"| node_whatsapp_service
node_compose -->|"runs"| node_main

click node_main "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/main.py"
click node_webhook "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/routes/webhook.py"
click node_message_models "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/models/message.py"
click node_multimodal_router "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/logic/multimodal_router.py"
click node_language_manager "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/logic/language_manager.py"
click node_whatsapp_service "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/services/whatsapp_service.py"
click node_cache_service "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/services/cache_service.py"
click node_llm "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/ai/llm.py"
click node_whisper_stt "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/ai/whisper_stt.py"
click node_elevenlabs_tts "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/ai/elevenlabs_tts.py"
click node_vision "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/ai/vision.py"
click node_settings "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/config/settings.py"
click node_base "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/database/base.py"
click node_models "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/database/models.py"
click node_repositories "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/database/repositories.py"
click node_helpers "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/utils/helpers.py"
click node_demo_bot "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/demo_bot.py"
click node_compose "https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_settings,node_compose toneBlue
class node_webhook,node_message_models toneAmber
class node_multimodal_router,node_language_manager toneMint
class node_whatsapp_service,node_cache_service,node_llm,node_whisper_stt,node_elevenlabs_tts,node_vision toneRose
class node_base,node_models,node_repositories toneIndigo
class node_helpers,node_demo_bot toneTeal
```

## Components

### Runtime

Application bootstrap and deployment entrypoints

- [App start](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/main.py): FastAPI bootstrap · Starts the service, wires configuration, database, Redis, and HTTP server setup. · `jeevo-backend/app/main.py`
- [Settings](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/config/settings.py): Config · Environment-driven configuration for credentials, infrastructure, and runtime settings. · `jeevo-backend/app/config/settings.py`
- [Compose](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/docker-compose.yml): Deployment · Container orchestration for local or deployed multi-service execution. · `jeevo-backend/docker-compose.yml`

### API

HTTP routes and request/response models

- [Webhook](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/routes/webhook.py): HTTP routes · Public WhatsApp webhook plus health and verification endpoints. · `jeevo-backend/app/routes/webhook.py`
- [Message models](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/models/message.py): Pydantic contracts · Request, response, and internal message structures used across the app. · `jeevo-backend/app/models/message.py`

### Domain

Core conversation logic and orchestration

- [Router](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/logic/multimodal_router.py): Message router · Chooses handling paths for text, audio, image, and other inbound modalities. · `jeevo-backend/app/logic/multimodal_router.py`
- [Language](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/logic/language_manager.py): Locale logic · Manages language preference and response localization behavior. · `jeevo-backend/app/logic/language_manager.py`

### Integrations

External service adapters for messaging, cache, and AI

- [WhatsApp API](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/services/whatsapp_service.py): Messaging client · Outbound integration to Meta WhatsApp Cloud API over HTTP. · `jeevo-backend/app/services/whatsapp_service.py`
- [Cache](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/services/cache_service.py): Redis session store · Redis-backed cache for session state and recent conversation context. · `jeevo-backend/app/services/cache_service.py`
- [LLM](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/ai/llm.py): AI adapter · Language model integration boundary for conversational assistance. · `jeevo-backend/app/ai/llm.py`
- [Speech-to-text](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/ai/whisper_stt.py): AI adapter · Audio transcription integration for voice message handling. · `jeevo-backend/app/ai/whisper_stt.py`
- [Text-to-speech](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/ai/elevenlabs_tts.py): AI adapter · Speech synthesis integration for spoken responses. · `jeevo-backend/app/ai/elevenlabs_tts.py`
- [Vision](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/ai/vision.py): AI adapter · Image understanding integration for multimodal inputs. · `jeevo-backend/app/ai/vision.py`

### Data

Database schema and persistence access

- [DB setup](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/database/base.py): SQLAlchemy bootstrap · Database engine and session setup for PostgreSQL access. · `jeevo-backend/app/database/base.py`
- [Schema](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/database/models.py): SQLAlchemy models · Persistent entities for users, conversations, reminders, alerts, and sessions. · `jeevo-backend/app/database/models.py`
- [Repositories](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/database/repositories.py): DB access layer · Repository boundary that encapsulates SQLAlchemy persistence operations. · `jeevo-backend/app/database/repositories.py`

### Support

Shared helpers and local tooling

- [Helpers](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/app/utils/helpers.py): Shared utils · Cross-cutting helper functions used by multiple modules. · `jeevo-backend/app/utils/helpers.py`
- [Demo bot](https://github.com/jpisop007/jeevo/blob/main/jeevo-backend/demo_bot.py): Local demo · Standalone bot entrypoint for local experimentation and testing. · `jeevo-backend/demo_bot.py`

## Connections

- 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.
