docs: triage Matrix inbox; lead Next with contact_type retirement
- ROADMAP: backlog backup-history collapse, tab-on-refresh, email cc-dedup (P2) - ROADMAP: mark in-app card intake done & live (v0.1.0:100); remove stale plan doc - AGENTS.md: reorder Current-state Next to lead with contact_type retirement
This commit is contained in:
Keysat
@@ -1,133 +0,0 @@
|
||||
# Plan: in-app business-card intake (mobile camera → transcribe → approve)
|
||||
|
||||
**Status:** PLAN — decisions locked 2026-06-20 (see end); awaiting Grant's go-ahead to build.
|
||||
**Goal:** a camera button in the mobile top bar (left of the quick-log pencil) → take a photo or
|
||||
pick one from the library → the **same** vision-transcribe → parse → fuzzy-match → edit/approve/reject
|
||||
flow the Matrix card intake runs (M3), surfaced as an inline mobile sheet instead of a Matrix thread.
|
||||
|
||||
## Why this is cheaper than it looks
|
||||
|
||||
The reusable core is already nio-free and already reachable from the CRM monolith:
|
||||
|
||||
- `server.py` **already** imports the Spark client: `sys.path.insert(.../ingest); import llm`
|
||||
(`server.py:6485`). `llm.chat_vision` (multimodal → Spark Control passthrough) is the exact call
|
||||
the bot's card OCR uses.
|
||||
- `backend/matrix_intake/parse.py` imports only `json`, `re`, `spark`; `spark.py` imports only
|
||||
`os`, `sys`, `llm`. **Neither imports `matrix-nio`.** So `server.py` can import `parse` +
|
||||
`spark` the same way it imports `llm`, with **no bot refactor and no matrix-nio in the CRM**.
|
||||
- Match (`find_intake_match` / `find_intake_candidates`) and the write
|
||||
(`/api/fundraising/log-communication`, create-if-missing + contact upsert + audit) are **already**
|
||||
in `server.py`. The fuzzy matcher just got the generic-word fix (v-next).
|
||||
- The whole `backend/` tree (incl. `ingest/` + `matrix_intake/`) is `COPY`'d into the s9pk image
|
||||
(`start9/0.4/Dockerfile:62`), so the imports resolve on the box at runtime.
|
||||
|
||||
So this is **one new endpoint + one new mobile component**, reusing everything downstream. No
|
||||
migration, no new dependency, no change to the live Matrix bot.
|
||||
|
||||
## Architecture decision
|
||||
|
||||
**Recommended (Option A): `server.py` imports `matrix_intake.parse` + `matrix_intake.spark`
|
||||
directly.** Add `backend/matrix_intake` to `sys.path` (guarded like the existing `ingest` insert)
|
||||
and `import parse, spark`. Pros: zero bot churn, reuses the tested transcribe + email-integrity
|
||||
parse verbatim, no divergence. Con: the CRM now imports two modules out of the bot package — a mild
|
||||
coupling, but they're pure (no nio, no CRM HTTP; we do NOT import the bot's `crm_client`).
|
||||
|
||||
**Alternative (Option B): extract a shared `backend/intake_core/`** (`vision.py` = transcribe,
|
||||
`extract.py` = parse/normalize/revise) that both the bot and `server.py` import. Cleaner ownership,
|
||||
but it refactors the live, working bot for no functional gain right now. **Defer** unless the
|
||||
coupling in A bites later (e.g. if the bot's `parse` grows nio-coupled helpers).
|
||||
|
||||
> Module-name caution (from the matrix-intake guide): the bot imports by **bare name** (`import
|
||||
> spark`, `import llm`, `import config`). `server.py` already has `ingest/` on its path (so `llm`,
|
||||
> `config`, `http_util` resolve). Adding `matrix_intake/` lets `parse`/`spark` resolve with **no
|
||||
> name overlap** against `ingest`'s modules — verified. Import only `parse` + `spark` (not
|
||||
> `crm_client`/`settings`/`bot`).
|
||||
|
||||
## Server: one new endpoint
|
||||
|
||||
`POST /api/intake/card` — authenticated **member+** (it's a UI feature for the team; NOT bot-gated,
|
||||
NOT admin-only). Body is JSON, image as base64 (no multipart parsing in the stdlib handler):
|
||||
|
||||
```
|
||||
{ "image_b64": "<base64>", "mime": "image/jpeg" }
|
||||
→ 200 { "transcription": "...",
|
||||
"proposal": { investor_name, contact_name, contact_email, contact_title,
|
||||
city, linkedin_url, phone, mobile, note },
|
||||
"match": { id, name } | null,
|
||||
"candidates": [ { id, name, score, matched_on }, ... ] }
|
||||
```
|
||||
|
||||
Handler flow (mirrors `bot.handle_card` → `handle_intake`, minus Matrix):
|
||||
1. Auth (reuse the standard authenticated gate).
|
||||
2. Decode + size-guard the base64; default mime `image/jpeg`.
|
||||
3. `transcription = spark.transcribe_card(image_b64, mime)` (Spark Control vision). On error → 502
|
||||
`{ ok:false, reason:"vision_unavailable" }`; on `<5` chars → 200 `{ ok:false, reason:"unreadable" }`.
|
||||
4. `proposal = parse.parse_message("New investor — from a business card:\n"+transcription, roster=None)`
|
||||
— the **email-integrity rule rides along** (an address/phone/LinkedIn is kept only if it literally
|
||||
appears in the transcription, never minted), exactly as in Matrix. `roster=None` for v1 (the
|
||||
team-roster framing is a Spark-side env; the box can pass None — prior parse behavior).
|
||||
5. `match = find_intake_match(...)`, `candidates = find_intake_candidates(...)` from the proposal's
|
||||
`investor_name`/`contact_email`.
|
||||
6. Return `{ transcription, proposal, match, candidates }`.
|
||||
|
||||
**Approve** reuses the existing write — the mobile sheet POSTs the (possibly-edited) proposal to
|
||||
`POST /api/fundraising/log-communication` with `create_investor_if_missing` (new) or the picked
|
||||
`_match_id`/candidate row (existing), tagged **`source="app_card"`** (a new provenance value
|
||||
distinct from `matrix_card`/`matrix_intake`). **Reject** is client-only (discard the sheet) — no
|
||||
server call, nothing written.
|
||||
|
||||
**No NL-edit for v1.** In a form UI, editing the fields directly is easier than chatting "change the
|
||||
email to…". The fields are inline-editable in the sheet. (A `/api/intake/card/revise` wrapping
|
||||
`parse.revise` is a possible later enhancement if Grant wants conversational corrections.)
|
||||
|
||||
## Mobile UI: one new component
|
||||
|
||||
`MobileCardCapture` in the shell top bar, **left of `MobileQuickLog`** (the cluster at
|
||||
`index.html:14609`). Reuses `<BottomSheet>`, `.sheet-input`, `StageChip`, and the New-investor
|
||||
sheet patterns (8g).
|
||||
|
||||
- **Trigger:** a camera-icon button + a hidden `<input type="file" accept="image/*">` —
|
||||
**omit `capture`** so iOS shows the native action sheet (Take Photo / Photo Library / Browse),
|
||||
satisfying "take a photo OR use an existing photo." (`capture="environment"` would force the camera
|
||||
and skip the library — not what we want.)
|
||||
- **On select:** read the file as a data URL; **downscale via `<canvas>` to ~2000px max dimension**
|
||||
before base64 (native, no library) — keeps the payload under the StartOS reverse-proxy body cap
|
||||
(the matrix-intake guide's known `413` risk) and the model downscales to ~2 MP anyway. Don't
|
||||
over-shrink (hurts OCR). Show a "📇 Reading the card…" loading state.
|
||||
- **POST** to `/api/intake/card`; on `unreadable`/`vision_unavailable` show a "try a clearer,
|
||||
well-lit, fill-the-frame photo" message with a Retake button (same UX as the bot's `📇` replies).
|
||||
- **Approval sheet** (the New-investor sheet, pre-filled from `proposal`): editable investor name +
|
||||
contact name/email/title/city/phone/mobile/LinkedIn; a small "Existing investor?" block when
|
||||
`match`/`candidates` came back (pick a candidate row, or "Add as new"); **Approve** → the
|
||||
log-communication write; **Reject/Retake** → discard.
|
||||
- **Icon:** reuse the proven `.quicklog-btn svg` sizing fix (explicit CSS `width/height` + `flex:none`)
|
||||
so the new camera SVG doesn't hit the same iOS sole-flex-child collapse.
|
||||
|
||||
## Scope / effort / risk
|
||||
|
||||
- **Server:** ~1 endpoint + the `parse`/`spark` import guard + an `app_card` source tag. Small.
|
||||
- **Frontend:** ~1 component (camera button + capture input + canvas downscale + approval sheet) +
|
||||
CSS for the button. Medium (the approval sheet is the New-investor sheet pre-filled).
|
||||
- **No** migration, **no** new dependency, **no** Matrix-bot change.
|
||||
- **Tests:** an endpoint test that stubs `spark.transcribe_card` (like `test_spark.py` does) and
|
||||
asserts the transcribe→parse→match shape + the email-integrity passthrough; the real vision/OCR
|
||||
path stays **live-smoke only** (same as Matrix M3). Frontend is inspection + on-device.
|
||||
- **Risks:** (1) large-image upload vs the reverse-proxy cap — mitigated by client-side canvas
|
||||
downscale; (2) iOS file-input behavior across Safari/standalone-PWA — verify on-device; (3) OCR
|
||||
accuracy is the **shared** Matrix limitation (resolution-bound; "fill the frame"), not new here;
|
||||
(4) the `parse`/`spark` import must be lazy/guarded so a dev `./start.sh` without Spark reachable
|
||||
still boots (the endpoint just 502s) — mirror the existing lazy `import llm` at `server.py:6485`.
|
||||
|
||||
## Decisions (locked, Grant 2026-06-20)
|
||||
|
||||
1. **Provenance tag = `source="app_card"`** — distinct from `matrix_card` / `matrix_intake`.
|
||||
2. **v1 = editable form fields only** — no conversational NL-edit on the card (no
|
||||
`/api/intake/card/revise`); the user taps a field and fixes it in the sheet. NL-edit can follow
|
||||
later if it proves wanted.
|
||||
3. **Access = any authenticated member** — the camera button + `POST /api/intake/card` use the
|
||||
standard authenticated gate (not admin-only, not bot-gated); a human still approves every write.
|
||||
4. **Delivery = the s9pk** (server endpoint + frontend) — a normal version bump → build → box
|
||||
install, like v99 (NOT bot-only like the Matrix M3).
|
||||
|
||||
Build scope is otherwise as specified above. Mobile-only (top-bar button); same captured fields +
|
||||
literal-in-source integrity rule as the Matrix card flow.
|
||||
Reference in New Issue
Block a user