Skip to content

Vendease Engineering Handover

Welcome. This site is the engineering handover for the Vendease repositories that make up the production back-office, written so that a new engineer can read one project's section and start contributing to it without further onboarding.

How to use this site

  • Joining the team or rotating onto a new service? Open the relevant section from the top nav. Each project has the same skeleton: Overview → Architecture & Technology → How It Fits With Other Systems → Repository Layout → Running, Building & Deploying → Operational Notes & Risks.
  • On call? Jump straight to the project's Operational Notes & Risks section. Known production-affecting incidents and their resolutions are recorded there; the Odoo runbook is the most detailed example.
  • Auditing where data lives? Each backend's section names its primary store, secondary stores, message buses, and integration partners. Use the search bar (top right) to find a service that owns a particular event or table.

Project map

Domain Repos What they own
Discover Fresh (WhatsApp grocery) Odoo, discover_fresh Customer ordering bot, delivery clustering, Odoo-side back office for orders/deliveries/invoicing
Procurement & Marketplace e-procurement-v2, procurement-integration-backend B2B procurement, carts, POs, invoices, claims, credit, BNPL
Inventory & Warehouse Inventory-backend, wms IMS (current), WMS (next-gen multi-tenant)
Payments & Integration vendease-payments-backend, vendease-integration-server Payment gateways, wallets, virtual accounts, settlements; Odoo↔platform sync
Core Platform core-services Identity, shared NestJS infrastructure
Odoo Tenant Tree vendease-odoo Customer-tenant Odoo customisations

Cross-cutting topology

A few things to internalise before reading any individual project:

  • Two procurement codebases coexist. e-procurement-v2 (Node 14, Express, Sequelize, NATS Streaming) is the older system of record. procurement-integration-backend (Node 18, NestJS, TypeORM, NATS JetStream) is a newer rewrite that overlaps significantly. Per-table and per-event ownership is being decided in flight; check both before assuming where a record lives.
  • Two inventory codebases coexist. Inventory-backend (IMS, Express + Inversify) is in production. wms (NestJS multi-tenant) is the next-gen platform shell — infrastructure is wired (TypeORM tenant DataSource, JetStream, Bull, Redis, JWT) but the warehouse domain itself is not yet implemented in src/.
  • Event bus split. NATS Streaming carries events between the older Express services. NATS JetStream (with core.*,payment.* subjects) carries events between the newer NestJS services. Bridging the two requires an explicit translator — there isn't an automatic one.
  • Odoo is the system of record for finance and logistics. Customer payments, sale orders, invoices, and delivery groups land in Odoo. The df_* modules in the Odoo repo are the only application-class layer; everything else is field/workflow tweaks on top of stock Odoo.
  • Discover Fresh is split across two repos. Odoo/df_* are the production addons. discover_fresh/ is the prototype/sandbox tree (WhatsApp bot logic, Jupyter demo, design docs). They must move together.

How this documentation is published

This site is built with MkDocs Material from the handover-docs/ directory of the Vendease/Odoo repository. The publish flow:

  1. Documentation lives in handover-docs/<project>/ directories, one per source repo.
  2. On push to main or discoverfresh of Vendease/Odoo, the deploy workflow at .github/workflows/deploy-handover-docs.yml builds the static site and publishes to GitHub Pages at https://vendease.github.io/Odoo/.
  3. Source repos that want to own their own section can drop the template at handover-docs/templates/source-repo-deploy-docs.template.yml into their own .github/workflows/ to sync their docs/ subtree on staging merges.

Editors who want to fix a typo or add a section can use the pencil icon in the top-right of any page; it links to the relevant Markdown file.

What is NOT here

  • Source code. This is documentation only. Each project section names its repository, branch conventions, and how to clone it.
  • Live credentials, deploy keys, or .env values. Configuration surface (which env vars are read) is documented; values are not.
  • Per-incident war-room notes. Resolved incidents that produce institutional knowledge (e.g. the Odoo BNPL receivable fix) are written up in each project's runbook. Day-to-day Slack threads, dashboards, and ticket trackers are not duplicated here.

If you find a gap, edit the relevant Markdown file and open a PR. The publish workflow is automatic once it lands.