Skip to content

Discover Fresh

Overview

discover_fresh is the working folder for the Discover Fresh product — Vendease's WhatsApp-native grocery ordering and delivery clustering bot. The project is not a deployed service in this directory; it is a prototype/sandbox tree that holds the prose specifications for the product, the conversation logic and helper functions used during prototyping, a demo Jupyter notebook that walks the system end-to-end, and a few standalone scripts that talk to a staging Odoo instance via XML-RPC.

The product itself solves Vendease's need to extend its grocery operation to consumers who chat via WhatsApp rather than use a portal. Customers describe what they want in natural language; the bot resolves products against the Odoo catalogue, asks for a delivery location, groups nearby orders into clusters within a 2.5 km radius to share delivery costs, takes payment via Paystack, and pushes everything (orders, payments, delivery groups) back into Odoo. The internal team works the resulting orders out of a custom Odoo module rather than a separate dashboard.

In the broader Vendease workspace, the productionised half of Discover Fresh lives in the Odoo addon df_discover_fresh (and siblings such as df_logistics, dispatch_vehicle) inside the Odoo/ repository. This folder is the design and prototyping counterpart: the documents agreed with the leadership team, the logic that informs the bot, and the demo materials used to walk through the system.

Architecture & Technology

Languages and runtimes

  • Python 3.13 (per the __pycache__ artefacts under logic/databases/).
  • Jupyter notebook (df_demo.ipynb) used as the demo and integration sandbox.
  • No requirements.txt, pyproject.toml, or setup.py is committed at the root — Python dependencies are imported ad-hoc from a wider environment (cassandra, pymongo, pika, redis, clickhouse_driver, elasticsearch, supabase, plus the LLM provider SDKs).

Conceptual stack documented for the product

The docs/SYSTEM_IMPLEMENTATION.md and docs/PRODUCT_DOCUMENT.md files describe the intended runtime stack:

  • FastAPI application backend (Python).
  • PostgreSQL with pgvector as the bot's primary store and semantic search index, with a read cache of products synced hourly from Odoo.
  • RabbitMQ for background jobs and reliable inter-component messaging (with dead-letter queues).
  • Meta WhatsApp Cloud API (WABA) for customer messaging.
  • OpenAI GPT-4o as the production LLM (older drafts reference DeepSeek on Baseten); a multi-provider abstraction allows alternate-provider fallback.
  • Supabase (PostgreSQL + pgvector) as a hosted alternative for the database tier in earlier drafts.
  • SerpApi (Google Maps) for resolving free-text addresses into coordinates for clustering.
  • Paystack for checkout links and payment confirmation webhooks.
  • Upstash Redis for short-lived session state.
  • ScyllaDB Cloud for chat history.
  • Odoo 17 Enterprise as the system of record (products, prices, stock, sale orders, payments, deliveries) — this is the existing Vendease Odoo instance, augmented with a custom Discover Fresh module.
  • Kubernetes (AWS or DigitalOcean) for hosting.

The implementation in this folder is selective: the conversation orchestration, clustering logic, geo-search, and product search all have working Python modules. The database utility layer covers many candidate stores (Scylla, Cassandra, MongoDB, Elasticsearch, ClickHouse, RabbitMQ, Redis, Supabase) so the demo can swap backends without rewriting business logic.

Capability layout

The Python source under logic/ splits into three buckets:

  • logic/functions/ — the bot's domain logic. ai_orchestrator.py runs the conversational state machine (start conversation, extract items, advance stages); cluster_engine.py is an in-memory clustering implementation that finds-or-creates a cluster within a 2.5 km radius using a centroid; geo_service.py, product_service.py, and session_service.py round out location resolution, semantic catalogue lookup, and session state; models.py defines Order, OrderStage, UserProfile, and Cluster dataclasses; db_client.py is the shared database accessor.
  • logic/llms/ — provider-agnostic LLM templates. Separate modules per LLM provider (OpenAI and others), plus llm_templates.py, text_llm_templates.py, image_llm_templates.py, multimodal_llm_templates.py, voice_llm_templates.py, video_llm_templates.py, agent_prompts.py, markdown_utils.py, and two README/guide markdown files (CONVERSATION_API_GUIDE.md, README_CONVERSATIONS.md). The naming pattern (llm_template_function, etc.) suggests the modules originate from a wider internal LLM toolkit and are vendored here so the demo can run.
  • logic/databases/ — utility modules per backend: scylla_utils.py, cassandra_utils.py, mongo_utils.py, elastic_search_utils.py, clickhouse_utils.py, rabbitmq_utils.py, redis_utils.py, supabase_utils.py, database_utils.py. Each exposes singleton-style cluster/connection helpers driven by environment variables.

The notebook df_demo.ipynb (~150 KB, multi-phase) walks through the system in stages — environment setup, mock infrastructure, then the conversational ordering flow against the logic/ modules. It is the primary executable demo.

How It Fits With Other Systems

Inside the Vendease platform

  • Odoo (existing Vendease instance) is the contractual integration point. Per docs/PRODUCT_DOCUMENT.md, the bot pulls products, prices, and stock from Odoo hourly via XML-RPC, and pushes orders, payments, customer records, and delivery group assignments back in real time. Sale orders are created as quotations, then confirmed when payment is verified, then invoiced and posted with the Paystack reference.
  • Custom Odoo module(s) add Discover Fresh-specific views (delivery groups, aggregated item lists, exception queue, dispatch workflow) on top of standard Odoo Sales, Inventory, Contacts, Payments, and Stock Picking. Those modules live in the sibling Odoo/ repository as df_discover_fresh and related addons; this folder is the design counterpart, not the addon source.
  • The standalone scripts in this folder (fix_payslip.py, plus the staging URL referenced in DEMO_SCRIPT.md) talk to the Odoo staging instance packetclouds-vendease-staging-28942807.dev.odoo.com using admin credentials inlined in source.

External integrations referenced in code/configs

  • Meta WhatsApp Cloud API — customer messaging substrate (documented; not wired into this Python code).
  • Paystack — payment links and webhook-driven confirmation (documented).
  • OpenAI — LLM provider for ordering, stage detection, and reply generation. The logic/llms/ templates also cover alternative providers for fallback.
  • SerpApi (Google Maps) — address resolution for clustering.
  • Supabase, ScyllaDB Cloud, Upstash Redis — externally hosted data tiers referenced in the cost estimates and database utility code.
  • AWS / DigitalOcean — target hosts for the FastAPI bot backend (per the cost section of PRODUCT_DOCUMENT.md).
  • A serpapi_debug.json sits at the root, a 34 KB debug payload from a SerpApi call captured during prototyping.

Shared libraries

  • The Python modules import from logic.base_functions.llms.llm_templates (in ai_orchestrator.py), implying a base_functions library that lives outside this folder. This folder vendors a partial copy under logic/llms/ rather than re-exporting from the upstream library.
  • No first-party Python package (@vendease/...) is published from this directory.

Repository Layout

discover_fresh/
  DOC.md                Working notes: feature/workflow descriptions for the Odoo
                        custom module — Exception Queue, Pending Approval, Weekly
                        Inventory Updates, Price History, plus 3PL/zone discussion
                        and rider/3PL fixture rows. Operational, not a spec.
  DEMO_SCRIPT.md        Step-by-step walkthrough for live demos against the
                        Odoo staging instance — order creation, delivery group
                        creation, PO generation, invoicing, dispatch, trip
                        lifecycle, vendor bills, vehicle expenses, reporting.
  df_demo.ipynb         Jupyter notebook driving the prototype end-to-end across
                        multiple phases (environment, conversation, clustering).
  fix_payslip.py        Standalone XML-RPC script that adds the admin user to the
                        Discover Fresh Operations Manager group on staging Odoo.
                        Inlines staging credentials.
  serpapi_debug.json    Captured SerpApi response (34 KB) from a debug session.
  image.png             A screenshot.
  docs/
    PRODUCT_DOCUMENT.md       Founders/leadership-facing product spec:
                              architecture diagram, services & integrations
                              with pricing, internal team workflow, weekly
                              schedule, exception handling, delivery model,
                              cost estimates, success metrics, 20-week
                              timeline, dependencies, risks.
    SYSTEM_IMPLEMENTATION.md  Technical specification — FastAPI / PostgreSQL+
                              pgvector / RabbitMQ / WABA / DeepSeek (Baseten or
                              OpenAI) / Paystack / Kubernetes — with project
                              structure, schema, queue design, state machine,
                              security, retry strategy, K8s deploy, env vars.
    CUSTOM_ODOO_MODULE.md     Specification for the custom Odoo 17 module that
                              the internal team uses to manage Discover Fresh
                              operations.
    ODOO_INTEGRATION.md       How the bot integrates with Odoo 17 Enterprise.
    ODOO_17_FINANCE_WALKTHROUGH.md  Finance/accounting walkthrough on Odoo 17.
    ODOO_TRANSITION_CALL_BRIEF.md   Briefing notes for the Odoo transition call.
    SYSTEM_IMPLEMENTATION.md, PRODUCT_DOCUMENT.md as above.
    phase_1_scoping.md, phase_2_scoping.md   Phased scoping docs.
    roadmap.md, demo_roadmap.md              Roadmaps.
  logic/
    functions/      ai_orchestrator.py, cluster_engine.py, geo_service.py,
                    product_service.py, session_service.py, models.py,
                    db_client.py
    llms/           Provider-agnostic LLM templates (OpenAI plus
                    alternative providers), plus media-modality templates
                    (text, image, multimodal, voice, video) and prompt
                    utilities.
    databases/      One utility module per candidate backend: Scylla,
                    Cassandra, Mongo, Elasticsearch, ClickHouse, RabbitMQ,
                    Redis, Supabase, plus a generic database_utils.py.
  .vscode/, .codegpt/  Local editor / extension state.

Running, Building & Deploying

This folder does not deploy. It is a hybrid of specifications, a Jupyter notebook, and helper Python modules that the notebook and prototyping scripts import. There is no Dockerfile, Procfile, Jenkinsfile, Kubernetes manifest, or CI configuration committed under this directory.

Working with the prototype

  • The notebook df_demo.ipynb is the primary entry point. It expects an environment with the Python packages used by the logic/ modules (Cassandra/Scylla driver, pymongo, pika, redis, supabase-py, elasticsearch, clickhouse-driver, the LLM provider SDKs, FastAPI tooling). Cells use %load_ext autoreload and %autoreload 2 so edits to logic/ modules pick up without restarting the kernel.
  • logic/databases/*.py modules read connection details from environment variables (e.g. utom_scylla_server_public_ip_address); these need to be set before the corresponding utilities will connect.
  • fix_payslip.py is run directly with python fix_payslip.py against the staging Odoo URL embedded in the file.

Configuration approach

There is no .env.sample or central configuration loader in this folder. Each utility module reads environment variables directly via os.environ.get(...). The architecture documents under docs/ enumerate the variables the production FastAPI bot would expect (database, Redis, RabbitMQ, WhatsApp, OpenAI, Paystack, SerpApi, Odoo XML-RPC).

Production deployment (per the design docs)

docs/SYSTEM_IMPLEMENTATION.md describes the intended deployment as Kubernetes on AWS or DigitalOcean, with the FastAPI app, RabbitMQ workers, and PostgreSQL+pgvector database. The 20-week phased timeline in docs/PRODUCT_DOCUMENT.md ends at "go-live"; this folder corresponds to the early phases of that plan.

Operational Notes & Risks

  • Inlined staging credentials. fix_payslip.py embeds the staging Odoo URL, database name, username (admin), and password (super@dmin) in plain text. The DEMO_SCRIPT.md reproduces the same login. These should not be committed to a tracked repository (or should be staging-only with no value if leaked).
  • Dependencies are implicit. No requirements.txt, pyproject.toml, setup.py, or Pipfile is checked in, so reproducing the demo environment requires reading every import in logic/ and installing the packages by hand. Python version is implicit from the __pycache__ directory names (3.13).
  • Vendored library copy. ai_orchestrator.py imports logic.base_functions.llms.llm_templates, but the package on disk is logic.llms. The demo will not run unaltered without the upstream base_functions library on PYTHONPATH. Either the import paths or the directory layout need to be reconciled before a fresh checkout will execute.
  • In-memory clustering. cluster_engine.py keeps _ACTIVE_CLUSTERS and _ORDER_DETAILS in module-level Python state. It is fine for a notebook demo but cannot survive a process restart and is not concurrency-safe. The production design moves clustering into PostgreSQL.
  • Stack drift between documents. docs/SYSTEM_IMPLEMENTATION.md lists DeepSeek-on-Baseten as the LLM stack and PRODUCT_DOCUMENT.md lists OpenAI GPT-4o; both are described as the chosen path in their respective documents. Treat document version dates and the working notes in DOC.md as authoritative for current direction.
  • Untracked debug assets. serpapi_debug.json (34 KB), image.png (16 KB), df_demo.ipynb (147 KB), .DS_Store files, __pycache__/ directories, .vscode/, and .codegpt/ are all checked in. Output cells in the Jupyter notebook can leak data; review before sharing externally.
  • No tests. There is no tests/ folder, no pytest.ini, no jest equivalent. Validation happens by running the notebook.
  • Documentation density vs implementation density. The docs/ folder contains ten substantial markdown files describing the system; logic/ contains the working pieces of a single conversational flow. The gap between specification and implementation should be assumed to be the active work area.
  • Odoo addon lives elsewhere. The custom Odoo module that DOC.md, DEMO_SCRIPT.md, and docs/CUSTOM_ODOO_MODULE.md describe is not in this folder. It lives in the sibling Odoo/ repository (df_discover_fresh, df_logistics, etc.). Changes to the bot or the module need to be coordinated across both trees.