pfm-ocr/docs/handover/README.md

Handover materials

Two deliverables, same content, different jobs.

File	What it's for
PFM-Scanner-Knowledge-Transfer.odp	30-slide deck (LibreOffice Impress). For the walkthrough session. Diagrams are native draw shapes, so it also opens in Draw.
PFM-Scanner-Handover-Document.odt	42-page document (LibreOffice Writer). For the person working alone, later. Adds an operational runbook, a troubleshooting guide, a glossary, and a full screenshot appendix.
PFM-Scanner-Ringkasan-Scope.odt	20-page Indonesian summary (LibreOffice Writer). The one to read first: the flow, the folder map, the ports, how to run each part and from which directory, how login and upload actually move data, then what is built versus what isn't.
*.pdf	Same files, for sharing with people who won't edit them.

All three are built entirely from what is committed in this repo. Nothing is invented. Screenshots are the real captures from screenshots/v2/ and screenshots/, taken on a real device against the live backend.

Before handing them over — fill these in

Three things the repo cannot know are marked [ TO FILL IN ]:

• Deck slide 1 / document cover — presenter name, handover date, successors.
• Deck slide 24 / document §15 — the access & credentials checklist is a checklist, deliberately unfilled. Don't type secrets into either file; use it as the agenda for a session where the successor logs into each one themselves.
• Document §12.5, §12.7, §15 — how the APK reaches store devices, whether any DB backup runs, and the current deployment state (which stores are live, on what hardware, since when).

Contents

Deck (30 slides) — 1–2 intro · 3–8 what exists + architecture and sequence diagrams · 9–11 the app on screen (shell, DO scan ×2) · 12–13 gateway + internal web tooling · 14–16 accuracy · 17–18 Product Scan + its screens · 19–21 data, ops, repo map · 22–24 gotchas + credentials · 25–30 roadmap, scope, first 30 days, index.

Document (42 pages) — §1–9 what exists · §10 accuracy · §11–13 setup, runbook, troubleshooting · §14–18 gotchas, credentials, roadmap, out-of-scope, first 30 days · Appendix A glossary · B command reference · C doc index · D the app screen by screen.

Regenerating

src/ holds the generators. Both emit flat-ODF XML that LibreOffice converts.

cd docs/handover/src

python3 prepare_assets.py     # once — builds shots_small/ from ../../../screenshots/
                              # (needs Pillow; nothing else here does)

python3 build_deck.py                                     # -> pfm-handover.fodp
libreoffice --headless --convert-to odp pfm-handover.fodp

python3 build_doc.py                                      # -> pfm-handover-doc.fodt
libreoffice --headless --convert-to odt pfm-handover-doc.fodt

shots_small/ is gitignored — it is display-resolution copies of screenshots already committed elsewhere in the repo, and embedding the originals at full size makes the .odp roughly 10MB for no visible gain.

The Indonesian summary has its own generator, same two-stage shape as the deck:

cd docs/handover/src
python3 build_ringkasan.py     # draws diagrams, crops them, builds the doc,
                               # writes ../PFM-Scanner-Ringkasan-Scope.{pdf,odt}

Its four diagrams are native shapes like the deck's, drawn in the same file that builds the document, cropped to img/ring-*.png. Edit the shape coordinates in build_ringkasan.py and re-run — there is no separate re-crop step.

Two layout constraints it works around, worth keeping if you edit it. Writer glues a heading to a full-width image below it, so a section opening with a diagram jumps to the next page and strands a half-empty one — newpage() makes that jump deliberate. And a sequence diagram wider than about 20cm shrinks below readable size once scaled into the A4 text column, so keep the crop narrow rather than the font large.

build_deck.py prints a text-overflow report for any frame whose content is estimated to exceed its box — anything over ~0.15cm is worth fixing before shipping.

If you change a deck diagram

The document embeds the deck's diagrams as PNGs from src/img/, cropped out of the deck PDF. Re-crop after any diagram change, or the two will disagree. The crop rectangles are in centimetres (deck page, x, y, w, h); build_doc.py resolves them by filename prefix, so the page number in the filename can change freely.

# after rebuilding the deck PDF
python3 - <<'PY'
import subprocess
DPI=200; K=DPI/2.54
crops={"flow":(3,1.35,4.40,22.70,2.90),"arch":(4,1.30,3.10,22.90,5.05),
       "sequence":(6,1.00,3.25,23.20,9.15),"layers":(14,1.35,4.25,22.70,7.00),
       "product":(17,1.35,4.25,22.70,2.20),"phases":(27,1.35,8.75,22.70,2.05)}
for n,(p,x,y,w,h) in crops.items():
    subprocess.run(["pdftoppm","-r",str(DPI),"-f",str(p),"-l",str(p),"-png",
        "-x",str(int(x*K)),"-y",str(int(y*K)),"-W",str(int(w*K)),"-H",str(int(h*K)),
        "pfm-handover.pdf","img/"+n],check=True)
PY

Note: LibreOffice installed from snap cannot read paths outside $HOME, so run the conversions somewhere under your home directory.

Editing directly in Impress/Writer is fine, but then the generators are stale — pick one as the source of truth rather than maintaining both.