Eight documents under docs/development/ confronting the approved business architecture with the audited code: 27-step plan, repository migration map, domain map, frontend/backend architecture, migration and test strategy, open questions. Reference document placed at the repository root.
189 lines
12 KiB
Markdown
189 lines
12 KiB
Markdown
# Open questions, contradictions and flagged decisions
|
|
|
|
Status: Step 0 deliverable, 2026-10-08. Two lists: (A) contradictions,
|
|
ambiguities or technically risky points found when confronting
|
|
`faunosteo-business-architecture.md` with the code and the audit, and (B)
|
|
questions for the developer that change architecture or development order.
|
|
Items that are merely interesting are left out.
|
|
|
|
## A. Contradictions, ambiguities, risky decisions
|
|
|
|
### C1. Vertebral formula shape (architecture §7.2 vs §23.2)
|
|
|
|
§7.2 shows `"vertebral_formula": { "C": 7, "T": 13, "L": 7, "S": 3, "Cd": 20 }`,
|
|
the same fixed five-key object as today's `VertebralFormula`. §23.2 asks to
|
|
"remove hard-coded five-region assumptions from generic domain code". The
|
|
canonical document must use an ordered list of regions `{ code, label_fr,
|
|
label_en, count }` and the report must store the region code, otherwise the
|
|
report schema keeps the `z.enum(['C','T','L','S','Cd'])` of
|
|
`observation.ts:7`. This plan assumes the ordered list. See also Q3.
|
|
|
|
### C2. Report-only manual points vs "report references an immutable sheet version" (§3.2 step 7, rule 3)
|
|
|
|
"A manually created point exists only in this report until promoted to a
|
|
personal sheet." Such a point is not in any sheet version, so the report
|
|
document must carry `localAnnotations[]` (geometry, view id, names, optional
|
|
finding free text) and the PDF must render them. The architecture does not
|
|
say where they live or how promotion rewrites the report (does the report
|
|
then reference a *new* version of the personal sheet?). Decision needed
|
|
before the report document v3 is frozen. See Q6.
|
|
|
|
### C3. Worker on day one (§21.1) vs PostgreSQL-backed jobs first (§22.3)
|
|
|
|
Not a contradiction in substance, but the monorepo tree lists `apps/worker`
|
|
as if it existed from the start. The plan creates it at the first job that
|
|
cannot be a SQL function (reminders / calendar sync).
|
|
|
|
### C4. Global client record shared across practitioners (§2.3, §6)
|
|
|
|
`clients` is "a global Faunosteo person record, not a copy per practitioner".
|
|
Two practitioners with a care relationship to the same person then edit the
|
|
same `first_name`/`last_name`/`notes_general`. Risks: one practitioner's edit
|
|
silently changes another's records; `notes_general` is clinical-adjacent and
|
|
must not be shared by default. The architecture also requires that identity
|
|
matching never reveals another relationship. The plan assumes: core identity
|
|
fields editable only by the creating practitioner or the claimed client
|
|
account, per-relationship notes in a separate table, and a verification flow
|
|
for linking. Q6 asks for confirmation. **Technically dangerous if left as a
|
|
plain shared row.**
|
|
|
|
### C5. Animal update rights "owner-controlled" (§17.3) with no client accounts in MVP (§20)
|
|
|
|
In the MVP the owner has no login. The rule "update is owner-controlled, with
|
|
practitioner update permitted only after a consultation context or explicit
|
|
owner permission" is unenforceable as written. Plan assumption: the
|
|
practitioner who created the animal (or an org member with the relationship)
|
|
can update it; owner control starts with the client portal (post-MVP).
|
|
|
|
### C6. What an unverified account may do (§3.1, §5)
|
|
|
|
"A non-verified account must not access full professional functionality."
|
|
Ambiguous: may it create clients/animals and drafts? May it complete a report?
|
|
Plan assumption: unverified = can set up profile, cabinet invitation
|
|
acceptance, browse public sheets; cannot create clients/animals/reports.
|
|
Affects the entitlement capability list. Confirm.
|
|
|
|
### C7. Vocabulary collision on "Observation" (audit 05 §1)
|
|
|
|
In the code an `Observation` is a group of zones + findings + severity +
|
|
comment; in the catalog "Observations / motifs de consultation" is a finding
|
|
category; the architecture lists "finding/observation/anamnesis tree". The
|
|
product vocabulary must fix one word for each before UI strings and schema
|
|
names are created in the SaaS. Plan uses: *Observation* = the report block
|
|
(unchanged), *Finding* = a leaf, *Finding category* = a tree root.
|
|
|
|
### C8. Multiple drafts per sheet (§7.1)
|
|
|
|
`anatomical_sheet_versions.status ∈ {draft, published, deprecated}` and
|
|
`current_version_id` on the sheet. Nothing says whether a sheet may hold more
|
|
than one draft at a time or who may edit a draft (creator only? org
|
|
members?). Plan assumption: at most one draft per sheet, editable by the
|
|
creator; a unique partial index enforces it.
|
|
|
|
### C9. Detail view storage: separate SVG asset vs viewBox on the parent asset (§7.3 vs audit 04)
|
|
|
|
`Horse_head.svg` is a full copy of `Horse.svg` with a different `viewBox` and
|
|
its own overlays (audit 04 §2). §7.2 gives every view its own
|
|
`svg_asset_id`. The future editor's "create detail from a zone" naturally
|
|
produces a `view_box` on the *same* asset. Plan assumption: `svg_asset_id`
|
|
nullable on detail views; null means "render the parent asset with this
|
|
`view_box`". The equine seed may keep two assets to stay byte-faithful to the
|
|
source files. Q5 asks which.
|
|
|
|
### C10. Edge Functions on self-hosted Supabase (§22.2, §31) on a 1 vCPU / 1 GB VPS (DEPLOY.md)
|
|
|
|
The current runbook provisions 1 vCPU / 1 GB. A self-hosted Supabase stack
|
|
(Postgres, GoTrue, PostgREST, Storage, Kong, Studio, edge-runtime, Realtime,
|
|
imgproxy) needs several GB of RAM and is operationally heavy for one person.
|
|
Either the VPS is upgraded, or the launch uses managed Supabase from day one
|
|
(the architecture's "stage 2" contract is the same schema anyway). This
|
|
changes Step 3 and the deploy runbook. Q2.
|
|
|
|
### C11. Free-plan quota counted on "completed" reports but editing a completed report is allowed 5 days (§1.2)
|
|
|
|
Consistent, but note the interaction with revisions: a restore of an old
|
|
revision after the 5-day window is an edit and must be denied for free
|
|
accounts. The plan treats *any* write to a completed report as
|
|
`reports.edit_after_free_window` after `free_edit_until`.
|
|
|
|
### C12. SVG sanitization "server-side before becoming available to others" (§15.3) vs direct-to-Storage uploads
|
|
|
|
Supabase Storage uploads go straight from the browser to the bucket. The
|
|
sanitizer must therefore run between upload and publication (quarantine
|
|
prefix + status column + policy), not "on upload". Designed in
|
|
`BACKEND_ARCHITECTURE.md` §5; flagged because a naive implementation would
|
|
ship the client sanitizer as the boundary, which the audit already marks
|
|
insufficient (F1).
|
|
|
|
### C13. CLAUDE.md rules that the migration necessarily breaks
|
|
|
|
- "domain/schema/*.ts are the data contracts, never change without bumping version": honoured (v3).
|
|
- "Ask before any change to importReportFromPdf or extractReportJson": honoured as a confirmation gate in the PDF step.
|
|
- "Never modify anatomy SVGs in public/species/": honoured; the importer reads, never writes them.
|
|
- "Each entry needs ≥1 source with citation": violated today by all 792 nodes (audit 05 §2.4). Either the rule is relaxed for the official seed or sources are authored before publication. Plan assumption: relaxed, `sources` optional, a warning in the editor.
|
|
- "React SPA exception" (BDR-001): still valid for `apps/app`; the public site is the SSR part.
|
|
|
|
### C14. Report locale not persisted (BDR-014) vs stored PDF artifacts
|
|
|
|
Server-stored PDFs must record the locale they were rendered in (artifact
|
|
metadata), otherwise re-rendering from the snapshot cannot reproduce the
|
|
document. Not a schema change on the report document; an artifact column.
|
|
|
|
## B. QUESTIONS POUR LE DEVELOPPEUR
|
|
|
|
Only questions whose answer changes the architecture or the order of work.
|
|
|
|
### Q1. Are there Faunosteo PDFs (report v2) in real use that must import into the SaaS?
|
|
|
|
- What: whether practitioners (or the client osteopath) hold exported PDFs today.
|
|
- Why: decides if the `v2ToV3` + legacy-id reconciliation path is production code with its own UI (quota, mapping review) or a dev-only adapter kept for regression tests (architecture §23.4 assumes no install base; CHANGELOG 0.1.0 says the same, but faunosteo.com is live per TODO Phase C).
|
|
- How to answer: ask the client; check the live site usage if any analytics exist (none in the repo).
|
|
|
|
### Q2. Hosting target for the first steps: self-hosted Supabase on an upgraded VPS, or managed Supabase?
|
|
|
|
- What: RAM/CPU available on the Scaleway VPS, and whether running the full Supabase Docker stack (plus Edge Functions) is acceptable operationally.
|
|
- Why: changes Step 3 (local dev is identical, but the deploy runbook, backups, Edge Function deployment and cost differ), and whether Edge Functions are used at all before the agenda/widget steps.
|
|
- How to answer: `DEPLOY.md` says 1 vCPU / 1 GB; confirm the plan for the box (`free -m`, `nproc` on the VPS) and the budget.
|
|
|
|
### Q3. Must the vertebral model support non-mammalian layouts (birds) in the MVP data model?
|
|
|
|
- What: the species list. README cites dog, cat, goat, cow, pig, rabbit, donkey, sheep; TODO Phase D cites "chicken". Birds have fused regions (notarium, synsacrum, pygostyle).
|
|
- Why: with an ordered region list (C1) any mammal fits; birds need fused/variable regions and change the picker. Deciding now avoids a document schema v2 right after launch.
|
|
- How to answer: product decision; the model in this plan (ordered region list with free codes) covers birds if region labels are free, so the answer only affects the picker UI.
|
|
|
|
### Q4. Is `public/pathology-editor.html` used today by an external domain expert?
|
|
|
|
- What: BDR-022 mentions a "domain expert" authoring the catalog; audit 11 could not tell whether the static tool is their workflow.
|
|
- Why: if yes, it must keep working against a JSON export of the official sheet during the editor-merge step and gets a documented export/import bridge; if no, it is deleted with the SVG editor.
|
|
- How to answer: ask the expert; check whether any `pathologies-equine-<timestamp>.json` exports exist outside the repo.
|
|
|
|
### Q5. Equine seed: two SVG assets (byte-faithful to `Horse.svg` and `Horse_head.svg`) or one asset + `view_box` for the head?
|
|
|
|
- What: storage shape of the official sheet v1.
|
|
- Why: affects the sheet document schema (`svg_asset_id` nullable), the renderer, the PDF detail view, and the "create detail view" editor feature. Two assets keep the files untouched; one asset halves storage and matches the future editor.
|
|
- How to answer: product/technical choice; recommendation is nullable `svg_asset_id` and two assets for v1 only.
|
|
|
|
### Q6. Report-only manual points and shared client records: where do they live?
|
|
|
|
- What: (a) schema and rendering of points created inside a report and not in any sheet (C2); (b) edit rights on global client core fields and whether `notes_general` is shared (C4).
|
|
- Why: both freeze the report document v3 and the client RLS, which are the two hardest migrations.
|
|
- How to answer: product decision. Recommendation: (a) `localAnnotations[]` in the report document, rendered in the PDF, promotion creates a new personal-sheet version and rewrites the report to reference it; (b) core identity editable by creator or claimed client only, notes per relationship.
|
|
|
|
### Q7. Phone verification and transactional email providers
|
|
|
|
- What: which SMS provider and which email provider (EU processing).
|
|
- Why: phone verification is a sign-up gate (§3.1) and a referral prerequisite; without a provider decision Step 7 ships email-only verification and the referral rules cannot be tested end-to-end.
|
|
- How to answer: business decision; GoTrue supports Twilio, MessageBird, Vonage, Textlocal.
|
|
|
|
### Q8. Public site framework: Next.js (architecture §21.2) or Astro SSR (global rule "Astro by default")?
|
|
|
|
- What: the framework of `apps/public-web`.
|
|
- Why: toolchain, Docker image, SEO tooling for the public-profile step. Does not affect the private app.
|
|
- How to answer: decide at that step; default to Next.js as approved unless the global rule is meant to override.
|
|
|
|
### Q9. Catalog anomalies to normalise or preserve in the official seed
|
|
|
|
- What: `sphenoid.categories[0].id === 'ssb-dysfunctions'` (same id as under `ssb`), degraded category slugs (`charni-res-vert-brales`, `cadrans-du-cr-ne`), zero `sources`, zero `description_en`.
|
|
- Why: the importer is deterministic and the seed v1 is immutable once published; renaming later means v2 of the official sheet. Finding paths in future reports anchor on these ids.
|
|
- How to answer: domain expert review of `docs/faunosteo-audit/05-findings-editor.md` §2.4; recommendation: fix the `ssb-dysfunctions` id to `sphenoid-dysfunctions` before v1 (no report references it yet), keep slugs verbatim with human labels.
|