farooqiearning/hm-water-system

Purpose and Runtime Entry Points

HM-Water is a water-delivery operations platform combining customer/order management, a static admin interface, WhatsApp event processing, and Gemini-driven conversational automation. The application entry point is main.py; its public FastAPI surface is organized under app/api/v1/, while the separate admin API and browser assets live in admin_panel/api/ and admin_panel/static/.

HTTP, Admin, and Security Boundary

Customer-facing/service APIs expose health, metrics, product/store, WhatsApp, and AI routes via app/api/v1/ai_router.py, app/api/v1/whatsapp.py, and app/api/v1/products.py. Administrative operations—including orders, customers, employees, catalog, coupons, audit logs, and WhatsApp connection management—are routed through admin_panel/api/. Authentication and authorization are centralized in app/auth/jwt.py, app/auth/rbac.py, and app/auth/sanitization.py.

Domain and Persistence Layer

Core business entities cover stores, products, customers, employees, orders, inventory bottles, ledgers, notifications, chat sessions, and WhatsApp messages/turns in app/models/. Application repositories provide domain-oriented access in app/repositories/order_repository.py, app/repositories/product_repository.py, and app/repositories/store_repository.py. The lower-level data core abstracts SQL access, transactions, Redis, and storage through data/database/, data/redis/, and data/storage/; database and Redis contracts are represented in schema/database/ and schema/redis/.

Business-Service Orchestration

Services are the principal business layer between APIs/agents and persistence. Order, product, store, employee, notification, analytics, activity, and admin workflows are implemented in app/services/order_service.py, app/services/product_service.py, and app/services/admin_service.py. Admin-specialized services separate management operations from the public API, including app/services/order_admin_service.py and app/services/catalog_admin_service.py.

WhatsApp Ingestion and Conversation Pipeline

Incoming WhatsApp traffic enters through app/api/v1/whatsapp.py and is handled by webhook and messaging services. app/services/webhook_service.py validates/processes webhook events; app/services/whatsapp_aggregation_service.py batches or debounces conversational input; app/services/whatsapp_service.py manages message delivery and flow. Connection lifecycle and the external WhatsApp client boundary are represented by app/services/whatsapp_connection_service.py and cwa_v2_3_sdk/client.py. Chat state is persisted and managed through app/services/chat_memory_service.py and chat-related models/data repositories.

AI Agent and Tool Execution Boundary

The AI subsystem separates orchestration, safety/context handling, tool registration, and execution in ai_agent/orchestrator.py, ai_agent/safety.py, and ai_agent/tool_executor.py. Gemini/Vertex integration is encapsulated in app/services/gemini_agent_service.py. Agent capabilities are exposed as controlled domain tools—orders, inventory, products, payments, customers, analytics, and stores—under app/tools/, with app/tools/registry.py acting as the application tool catalog. This boundary prevents model-driven flows from directly owning persistence logic.

Infrastructure and External Dependencies

The production runtime is containerized by Dockerfile and composed with PostgreSQL and Redis using docker-compose.yml. Redis supplies caching, locks, pub/sub, queues, and rate limits through data/redis/; the app-level cache client is app/cache/redis_client.py. Object storage supports local and MinIO providers in data/storage/local_provider.py and data/storage/minio_provider.py. Runtime configuration is environment-first with fallback configuration in config/settings.py, config/ai.py, and config/cwa.py; external integrations include Google Vertex AI/Gemini, WhatsApp via the CWA SDK, PostgreSQL, Redis, and optionally MinIO.