284 lines
14 KiB
Markdown
284 lines
14 KiB
Markdown
# BizMatch Phase 2 — Broker Workflow App
|
|
|
|
Module 1: foundation (Docker Compose, PostgreSQL, schema, migrations, login).
|
|
Module 2: business scan (NAS -> DB) and the first UI.
|
|
Module 3: recursive file listing, PDF streaming from the NAS and the ported
|
|
pdf.js viewer.
|
|
Module 4: the buyer side — buyers, contacts, NDA rounds, deals, the guided
|
|
"New inquiry" flow with duplicate detection and the deal status transitions.
|
|
|
|
The UI and all domain constants are English.
|
|
|
|
## Setup on 192.168.100.99 (Ubuntu 24.04)
|
|
|
|
Prerequisite: Docker + Compose plugin (`sudo apt install docker.io docker-compose-v2`).
|
|
|
|
```bash
|
|
# Unpack the project, then:
|
|
cd bizmatch-app
|
|
cp .env.example .env # optionally adjust DB_PASSWORD
|
|
docker compose up -d --build
|
|
```
|
|
|
|
The app applies all migrations on start and then listens on
|
|
`http://192.168.100.99:8090`.
|
|
|
|
> **Upgrading from Module 1:** `001_init.sql` was rewritten in place (German
|
|
> constants -> English). Applying it needs a fresh database:
|
|
> `docker compose down -v && docker compose up -d --build`. The DB held no
|
|
> production data yet, so there is nothing to migrate.
|
|
|
|
### Schema notes
|
|
|
|
`001_init.sql` holds the full base schema (Buyer / Contact / NDA / Deal /
|
|
Business / Note / Todo / Document / ExtractionJob / Staff) and is never edited
|
|
again. `002_buyer_fields.sql` adds the fields the buyer side actually collects
|
|
and is purely additive, so it applies to an existing database:
|
|
|
|
| Table | Added |
|
|
| --------- | ------------------------------------------------------------------------------------ |
|
|
| `contact` | `cell` |
|
|
| `buyer` | `address`, `state`, `background_experience`, `how_heard`, `interested_in_updates` |
|
|
| `nda` | `total_purchase_price`, `down_payment`, `intro_date` |
|
|
|
|
`003_interested_in_updates_nullable.sql` then drops the `NOT NULL` and the
|
|
default from `buyer.interested_in_updates`: the value comes off scanned intake
|
|
sheets where the field is frequently blank, so `NULL` means "not answered" and
|
|
has to stay distinct from `false` ("explicitly no"). The buyer detail shows it
|
|
as a Yes / No / not answered control, and `PATCH /api/buyers/:id` accepts all
|
|
three. The two price fields stay `text` on purpose: the paper forms contain entries like "1.2M + inventory" that no
|
|
numeric type survives. The migration also adds the three index expressions the
|
|
duplicate check needs (`lower(btrim(name))` and the digits-only phone/cell).
|
|
|
|
First smoke test:
|
|
|
|
```bash
|
|
curl http://localhost:8090/api/health
|
|
# -> {"ok":true}
|
|
|
|
# Create the three staff members (adjust the names):
|
|
curl -X POST localhost:8090/api/staff -H 'content-type: application/json' -d '{"name":"Chris"}'
|
|
curl -X POST localhost:8090/api/staff -H 'content-type: application/json' -d '{"name":"..."}'
|
|
```
|
|
|
|
## Dev mode (without the app container)
|
|
|
|
```bash
|
|
docker compose up -d db # database only
|
|
npm install
|
|
set -a; source .env; set +a
|
|
npm run dev # tsx watch, migrations run on start
|
|
|
|
# second terminal — frontend with hot reload, /api is proxied to :8090
|
|
cd web && npm install && npm run dev
|
|
```
|
|
|
|
## NAS mount
|
|
|
|
Mount it on the host via NFS, e.g. in `/etc/fstab`:
|
|
|
|
```
|
|
<truenas-ip>:/mnt/<pool>/bizmatch /mnt/bizmatch-nas nfs ro,soft,timeo=100 0 0
|
|
```
|
|
|
|
The compose file already passes `NAS_ROOT` (default `/mnt/bizmatch-nas`) into the
|
|
app container. Write access (NDA filing) comes in module 6 — then replace `ro`
|
|
with `rw` and limit the permissions to the two write paths.
|
|
|
|
### Business directories
|
|
|
|
Directly below `NAS_ROOT` there are three status directories; every immediate
|
|
subdirectory of those is one business. The directory names are configurable
|
|
(they contain spaces and are treated as opaque strings):
|
|
|
|
| Env var | Default | Business status |
|
|
| ------------------ | -------------- | --------------- |
|
|
| `NAS_DIR_ACTIVE` | `AAA = ACTIVE` | ACTIVE |
|
|
| `NAS_DIR_SOLD` | `AAA = SOLD` | SOLD |
|
|
| `NAS_DIR_INACTIVE` | `AAA = INACTIVE` | INACTIVE |
|
|
|
|
The scan is idempotent: existing rows are matched by name and only updated when
|
|
`nas_path` or `status` changed. Businesses that exist in the DB but no longer on
|
|
disk are kept and only reported as a warning in the log. A missing configured
|
|
directory aborts the scan with an error naming the path.
|
|
|
|
## Moving to the AI machine (later)
|
|
|
|
1. `docker compose down` on .99
|
|
2. Take a dump: `docker compose exec db pg_dump -U bizmatch bizmatch > backup.sql`
|
|
3. Copy the project folder to the AI machine, run `docker compose up -d --build`
|
|
4. Restore the dump: `docker compose exec -T db psql -U bizmatch bizmatch < backup.sql`
|
|
|
|
## API (as of module 4)
|
|
|
|
| Method | Path | Purpose | Session |
|
|
| ------ | --------------------------- | ------------------------------------------------ | ------- |
|
|
| GET | /api/health | liveness incl. DB check | no |
|
|
| GET | /api/staff | staff list | no |
|
|
| POST | /api/staff | create staff member `{name}` | no |
|
|
| POST | /api/login | login via `{staff_id}` → session cookie | no |
|
|
| GET | /api/me | signed-in staff member | yes |
|
|
| POST | /api/logout | sign out | yes |
|
|
| POST | /api/businesses/scan | scan the NAS → `{scanned, inserted, updated, missing}` | yes |
|
|
| GET | /api/businesses | list `?status=&search=` + counts per status | yes |
|
|
| GET | /api/businesses/:id | single business incl. `nas_path` | yes |
|
|
| GET | /api/businesses/:id/files | recursive listing, max depth 3 (PDFs first) | yes |
|
|
| GET | /api/businesses/:id/file | stream one file, `?path=<relative>` | yes |
|
|
| GET | /api/businesses/:id/deals | buyer activity on one business, newest first | yes |
|
|
| GET | /api/buyers | list `?search=&status=` + counts per buyer status | yes |
|
|
| GET | /api/buyers/duplicates | candidates for `?email=&name=&phone=` | yes |
|
|
| POST | /api/inquiries | guided new-inquiry flow (one transaction) | yes |
|
|
| GET | /api/buyers/:id | buyer incl. `contacts[]` and `ndas[].deals[]` | yes |
|
|
| PATCH | /api/buyers/:id | identity fields + status (+ `end_open_deals`) | yes |
|
|
| POST | /api/buyers/:id/contacts | add a contact | yes |
|
|
| PATCH | /api/contacts/:id | edit a contact (incl. `is_primary`) | yes |
|
|
| PATCH | /api/ndas/:id | edit one NDA round | yes |
|
|
| POST | /api/ndas/:id/deals | add a business to an existing round | yes |
|
|
| POST | /api/deals/:id/status | `{status, comment?}` — transition + note | yes |
|
|
| GET | /api/deals/:id/notes | notes of one deal, newest first | yes |
|
|
|
|
Everything except health, staff (GET+POST) and login requires the session
|
|
cookie; without it the API answers `401`.
|
|
|
|
### Buyer side (module 4)
|
|
|
|
Domain rules, all enforced in the API:
|
|
|
|
* **buyer** is the buying party, **contact** are its 1..n people, **nda** is one
|
|
inquiry round (a returning buyer signs a *new* NDA), **deal** is
|
|
buyer↔business inside one round. There is deliberately no uniqueness on
|
|
`(buyer_id, business_id)` — a returning buyer gets a new round with new deals
|
|
and the history stays visible.
|
|
* Deal flow `NEW → INFO_SENT → DUE_DILIGENCE → LOI → CLOSING`, `ENDED` from
|
|
anywhere. `POST /api/deals/:id/status` rejects only a no-op (`409`);
|
|
everything else is allowed on purpose, because corrections have to be
|
|
possible. Entering `INFO_SENT` sets `follow_up_at = today + 14`, entering
|
|
`ENDED` clears it.
|
|
* When an NDA becomes `SIGNED` it gets a `signed_at` (default today) and its
|
|
buyer is set back to `ACTIVE`.
|
|
* Deactivating a buyer with `{"status":"DEACTIVATED","end_open_deals":true}`
|
|
ends all their non-`ENDED` deals; the response always carries
|
|
`open_deal_count` so the UI can warn first.
|
|
|
|
`GET /api/buyers/duplicates` matches exactly, never fuzzily: normalised e-mail
|
|
(`lower(btrim(…))`), case-insensitive contact name, and phone **or** cell
|
|
compared digits-only, so `(361) 555-0101` and `3615550101` are the same number.
|
|
Numbers with fewer than 7 digits are ignored. A candidate reports every reason
|
|
it matched in `matched_on`.
|
|
|
|
`POST /api/inquiries` is the guided flow and runs in one transaction. Without
|
|
`buyer_id` it creates buyer + primary contact; with `buyer_id` it reuses the
|
|
buyer and only adds the contact when no existing contact of that buyer has the
|
|
same normalised e-mail or the same name. It then creates the NDA round and one
|
|
deal, and returns
|
|
`{buyer_id, nda_id, deal_id, created:{buyer, contact}}`. The optional
|
|
`backfill` block (`deal_status`, `nda_status`, `signed_at`, `nda_nas_path`)
|
|
files a paper record in its real state — a backfilled `INFO_SENT` still arms
|
|
the 14-day follow-up, later statuses do not.
|
|
|
|
### File listing and streaming
|
|
|
|
`/files` walks the business directory recursively (max depth 3), skipping
|
|
dotfiles, dot-directories and symlinks, and returns
|
|
`{ path, size, mtime }` with `path` relative to the business directory and
|
|
always posix-separated. PDFs come first, then everything else, each group
|
|
alphabetical.
|
|
|
|
`/file?path=…` streams one of those files straight from disk
|
|
(`createReadStream`, never buffered):
|
|
|
|
* the path is resolved against `nas_path` and then `realpath`-validated to be
|
|
inside `realpath(business dir)`. Absolute paths, `..`, leading dots, empty
|
|
paths and symlinks pointing out of the tree get `400`; a missing file `404`.
|
|
* single-range HTTP `Range` requests answer `206` with `Content-Range`,
|
|
unsatisfiable ones `416`.
|
|
* `ETag` is derived from mtime + size, `If-None-Match` answers `304`.
|
|
* `.pdf` is served as `application/pdf` (inline), anything else as
|
|
`application/octet-stream` with `Content-Disposition: attachment`.
|
|
|
|
## Frontend
|
|
|
|
`web/` is a Vite + React + TypeScript app with Tailwind v4 (no router, no state
|
|
library). The header carries the two nav entries **Businesses** and **Buyers**;
|
|
routing is a hand-rolled `{view, id}` state in `App.tsx`. Views:
|
|
|
|
* login ("Who is working?")
|
|
* business list (tabs with counts, search, "Scan NAS now")
|
|
* business detail — a master-detail split filling the viewport: file table
|
|
left, PDF viewer right, plus a collapsed "Buyer activity" panel linking to
|
|
the buyers who were introduced to this business
|
|
* buyer list (status chips with counts, search over company/contact/e-mail,
|
|
"New inquiry")
|
|
* new inquiry — contact + business picker; while typing a known name, e-mail or
|
|
phone a warning panel lists the duplicate candidates with "Use this buyer"
|
|
(locks the buyer, shown as a chip with an undo) or "Create new buyer anyway".
|
|
The collapsible "Backfill existing deal (paper records)" section files
|
|
historic deals in their real state.
|
|
* buyer detail — status header with Deactivate/Reactivate (warns about the open
|
|
deals it would end), inline-editable identity panel, contacts with a primary
|
|
star, and the NDA rounds newest first: editable round fields, the deals of
|
|
the round with an action menu (next step, "End deal", plus a "Correct to…"
|
|
section) that opens a comment dialog, and a collapsed read-only notes list
|
|
per deal.
|
|
|
|
In dev, Vite proxies `/api` to `http://localhost:8090`. In production the
|
|
Fastify app serves `web/dist` via `@fastify/static` with an SPA fallback to
|
|
`index.html` for all non-`/api` routes; the Dockerfile builds the frontend in
|
|
its own stage and copies `web/dist` into the runtime image.
|
|
|
|
### PDF viewer
|
|
|
|
The viewer is the proven one from the phase-1 Deno desktop app (see
|
|
`viewer-phase1/`), ported nearly byte-identical. It lives in
|
|
`web/public/viewer/` as plain, unbundled ES modules — Vite serves `public/`
|
|
as-is, so the same files work in dev and prod. The React app embeds it in an
|
|
`<iframe>`:
|
|
|
|
```
|
|
/viewer/index.html?file=<urlencoded /api/businesses/:id/file?path=...>
|
|
```
|
|
|
|
The page refuses any `file` value that is not a root-relative `/api/` path, and
|
|
the iframe is same-origin, so the normal session cookie authenticates it.
|
|
|
|
`web/public/pdfjs/` holds the pdf.js runtime, copied out of
|
|
`node_modules/pdfjs-dist` (pinned to exactly 6.1.200) by
|
|
`web/scripts/copy-pdfjs.mjs`, which runs on `predev` and `prebuild` — also
|
|
inside the Docker web stage. The directory is generated and git-ignored:
|
|
|
|
```
|
|
web/public/pdfjs/legacy/ pdf.min.mjs + pdf.worker.min.mjs
|
|
web/public/pdfjs/wasm/ CCITT-G4/JBIG2, JPEG2000 and ICC decoders
|
|
web/public/pdfjs/standard_fonts/ standardFontDataUrl
|
|
web/public/pdfjs/iccs/ iccUrl
|
|
```
|
|
|
|
The `wasm/` directory is what makes scanned B/W pages render at all; without it
|
|
pdf.js fails the decoders silently and shows blank white canvases.
|
|
|
|
## Structure
|
|
|
|
```
|
|
migrations/ numbered SQL migrations
|
|
001_init.sql full schema
|
|
002_buyer_fields.sql buyer-side fields from the NDA form + intake sheet
|
|
003_…_nullable.sql interested_in_updates becomes tri-state
|
|
src/
|
|
config.ts env configuration
|
|
db.ts pg pool, query helpers, withTransaction
|
|
session.ts the staff-id cookie
|
|
migrate.ts migration runner (transactional, advisory lock)
|
|
business-scan.ts NAS scan, recursive listing, safe file path resolution
|
|
server.ts Fastify app (health, staff, login, businesses, file, static)
|
|
buyer-routes.ts buyers, contacts, NDA rounds, deals, the inquiry flow
|
|
web/
|
|
scripts/copy-pdfjs.mjs pdfjs-dist -> public/pdfjs/ (predev + prebuild)
|
|
public/viewer/ standalone, unbundled pdf.js viewer page
|
|
public/pdfjs/ generated, git-ignored pdf.js runtime
|
|
src/api.ts typed API client
|
|
src/App.tsx session gate + nav + view switch
|
|
src/components.tsx shared bits (badges, inline fields, business picker, dialog)
|
|
src/views/ Login, Businesses, BusinessDetail, Buyers, BuyerDetail, NewInquiry
|
|
viewer-phase1/ reference copy of the phase-1 desktop viewer
|
|
```
|