# Modules Handbook

How to write and organise the **Property Lab AI Peta** module docs. Each doc is a short, practical reference for **one module** — what it does, how it works (in short), and the full list of code files involved (backend, frontend, migrations, seeders, routes).

This file is the **guideline only** — there is no module index here. To find a module, browse the folders below.

## Structure & conventions

- **One folder per module**, with the doc itself as `readMe.md` inside it — e.g. `manage/leads/readMe.md`, `shared/media/readMe.md`. Do **not** leave a bare `module.md` at a portal root.
- **Group related modules under a shared parent folder.** Modules that belong to the same area live together. Current groupings:
  - `manage/people/` → `admins/readMe.md` + `roles/readMe.md` (admin accounts + their permissions)
    + `merge-requests/readMe.md` (the duplicate-account queue — identity governance)
    + `groups/readMe.md` (agency multi-tenancy — the group/team structure those admins and leads are scoped to).
  - `manage/membership/` → `members/readMe.md` + `memberships/readMe.md` (tiers + enrolling members).
  - `manage/events/` → `funnels/readMe.md` (the funnel program — slots / sessions / webinars, incl. per-slot members-only gating) + `funnel-whatsapp/readMe.md` (its WhatsApp automation) + `slot-posters/readMe.md` (per-slot poster upload/AI-generation + the landing hero/og:image). The parent folder holds no `readMe.md` of its own.
  - `manage/messages/` → `whatsapp/readMe.md` (+ its own sub-docs) + `messenger/readMe.md` (the two channel engines). Here the parent **does** hold a `readMe.md`: the two modules share one sidebar group, one inbox and one set of URLs, and that shared IA has no other home.
  - `manage/appointment-engine/` → the AI Appointment System. The parent **does** hold a `readMe.md` (the module front door), beside five reference docs — `data-model.md`, `bridges.md`, `runner.md`, `services.md`, `surfaces.md` — a `changelog.md`, the original build brief `spec.md`, and `ai-agent/readMe.md` for the workflow builder. It is split because one file could not carry a 24-table schema, the CRM/WhatsApp/voice bridges and a 20-handler runner without becoming unnavigable.
  - `manage/payments/` → `gateways/readMe.md` (the credential + driver registry every payment runs on) + `payment-links/readMe.md` (**Payment Items** — what is for sale and how each thing is paid for) + `payment-automation/readMe.md` (a payment item's WhatsApp + AI-call automation for its buyers — the item's Show page) + `purchase-histories/readMe.md` (the payments ledger) + `unreconciled/readMe.md` (money the gateway reports that the system could not place) + `transfer-receipts/readMe.md` (the Touch 'n Go lane's queue — a customer's "I've paid" becomes a sale only when an admin names the buyer and the item) + `wallet-statements/readMe.md` (the other half of that lane: reading the owner's own wallet export, the only proof money actually arrived) + `phase-e-convergence.md` (how those two halves become ONE payment, and the mailbox poller).
- **Top level is grouped by portal / library**, plus one ops folder:
  - `manage/` — the admin portal (`/manage/*`, behind `auth` + `admin` middleware).
  - `main/` — the public / user-facing portal (`/`, login, member area).
  - `shared/` — cross-portal features and `Src\Common` services (e.g. `Media`, `Profile`). A **shared frontend component** belongs here too once a second module depends on it (e.g. [`image-lightbox`](/docs/modules_handbook/shared/image-lightbox/readMe.md), used by both the slot-poster modal and the message threads): documenting it inside either consumer leaves the other's maintainer unable to find its contract. Same rule as a service — one doc, with a `Reference usage` section, and a one-line pointer from each consumer.
  - `production-setup/` — **the one exception to the rules above.** Ops runbooks for the long-running daemons the app needs in production, one flat file per process: [`horizon.md`](/docs/modules_handbook/production-setup/horizon.md) (queue workers + the zero-downtime deploy footgun), [`reverb.md`](/docs/modules_handbook/production-setup/reverb.md) (the WebSocket server behind live inbox updates) and [`scheduler.md`](/docs/modules_handbook/production-setup/scheduler.md) (`schedule:work` — what puts time-driven commands in motion). These are **not modules**: they describe *processes on a box*, not a feature with controllers/models/views, so there is no `readMe.md` here and the three core sections below do not apply. A runbook explains what must be running, how to deploy it, and how to tell it is down; the *behaviour* it serves is documented with the module that owns it (e.g. real-time lives in [`manage/messages/whatsapp/realtime.md`](/docs/modules_handbook/manage/messages/whatsapp/realtime.md), which `reverb.md` defers to). Add a file here only for another such daemon.
- **Extra files for a module** (commands, cheat-sheets, diagrams) live in the same folder beside its `readMe.md` — e.g. `manage/messages/whatsapp/command.md`.
- **Cross-link with absolute paths** from the repo root (`/docs/modules_handbook/...`) so links survive a file moving folders.

## How to read each doc
Every module `readMe.md` has the same core sections:
1. **What it does** — the purpose in a few sentences.
2. **How it works** — the request / data flow in short bullets.
3. **Related files** — every file involved, grouped by Backend / Frontend / Migrations / Seeders / Routes.

**Shared services** — a reusable service used by other modules (e.g. `MediaService`) — **must also include a `Reference usage` section**: a pointer to a real consumer that shows the canonical way to use the service, instead of abstract API notes. For example, the [Media](/docs/modules_handbook/shared/media/readMe.md) doc's *Reference usage* points to [Profile](/docs/modules_handbook/shared/profile/readMe.md)'s avatar / ID upload. Keep that example current — if the original consumer goes away, repoint it at another real caller.

> Docs cross-reference each other. The lead funnel spans both portals: the **Main** [Landing & Lead Capture](/docs/modules_handbook/main/landing-lead-capture/readMe.md) module *captures* leads, and the **Manage** [Leads](/docs/modules_handbook/manage/leads/readMe.md) module *manages* them — the two docs link to each other.