Seller-Admin-Tools

The weekly ritual for an enterprise seller is predictable: pull the pipeline CSV from the CRM, write the forecast narrative to the manager, assemble the QBR deck for the quarterly review, build the account plan for priority deals. Each artifact draws on the same underlying math — bucket rollups, week-over-week deltas, obligation-to-capability crosswalks — but is typically assembled by hand from the same export. Seller Admin Tools automates that path. Local, offline, deterministic, and vendor-neutral: no column names are hard-coded anywhere; a mapping screen translates any CRM export to a canonical schema, with saved profiles that make the following week's re-import zero-click. Adapted from an enterprise security-sales methodology, then de-branded and generalized before public release. The original four-session Streamlit build was ported to FastHTML 0.14.11 — specifically for offline-first operation with no CDN dependencies — then hardened through a security review. 72 commits · 10 PRs · 3 active days.

Four feature sessions built the four tools against a set of PRDs: ingest and column mapping, forecast narrative, QBR assembler, then account plan. After the build sessions, ten pull requests closed out correctness, security, accessibility, and packaging work. The core layer is pure Python functions over pandas 3.0 DataFrames and SQLite — fully exercised headlessly by pytest with no UI dependencies. The web layer is a thin FastHTML ASGI app; routes render strictly from view models in core/views/ so on-screen numbers and export artifacts share a single rendering path and cannot disagree. All behavior-driving logic — stage buckets, risk thresholds, coaching asks, narrative templates, alias normalization, regulatory obligation maps, and product crosswalk — lives in six YAML files in config/ read at call time. Changing a CRM format is a column remap; changing a threshold is a YAML edit; adding a regulatory framework is a new entry in obligation_map.yaml. No Python changes required for any of those. The Streamlit-to-FastHTML migration was driven by one constraint: the offline invariant needed to be mechanically enforced rather than advisory. FastHTML's CDN-header suppression config plus a startup assert at web/server.py made that possible — the server refuses to start if any response header references an external URL.

Key modules

Key features

• LocalOnlyMiddleware rejects any request whose Host header is not a loopback address (127.0.0.1 / localhost / ::1) — closing the DNS-rebinding attack surface before any route handler is reached.
• All mutating requests (POST, PUT, PATCH, DELETE) require a same-origin Origin or Referer header. Missing header → 403. The check survives the SELLER_ADMIN_TOOLS_ALLOW_REMOTE=1 remote-access mode.
• A startup assert scans all HTTP response headers at boot and raises RuntimeError immediately if any src= or href= value contains an external URL — making the offline invariant a process-level gate, not a policy.
• A socket-guard test monkeypatches socket.socket to raise, then runs a full narrative generation pass. Kept green as a CI hard invariant: a network call anywhere in the core path would fail this test.
• Dependency floors in constraints.txt: pillow>=12.3.0 (image-decoding advisories below that threshold, pulled by python-pptx) and python-multipart>=0.0.31 (DoS-class advisories below that threshold on the file-upload path, pulled by FastHTML/Starlette).
• Security-audit CI (.github/workflows/security-audit.yml) runs pip-audit plus the full pytest gate on every push, pull request, and weekly cron.
• Real CRM exports and the runtime database (data/agents.db) are git-ignored. Sample data is entirely fictional — 40 pipeline rows and 5 account-facts rows designed to exercise every failure class in the ingest path.

• The Streamlit-to-FastHTML migration happened mid-project after the offline requirement crystallized — Streamlit can't vendor its frontend dependencies, FastHTML can. The startup assert and LocalOnlyMiddleware came out of a security review on the same day, from the same session.
• The snapshot store's as_of_date model — using the week the data represents rather than when it was imported — sounds like a minor detail until you batch-import three weekly CSVs and discover that imported_at collapses all three to the same timestamp, making the week-over-week trend flatline.

• A hard invariant is worth more than a policy: the offline requirement became real only after the startup assert was added. 'We don't pull from CDNs' is a statement; 'the server refuses to boot if a CDN reference appears in any header' is a control.
• Config-not-code is an underrated portability strategy. When stage labels, risk thresholds, coaching asks, and regulatory frameworks live in YAML files read at call time, adapting the tool to a different CRM or methodology is an edit session, not a port. The de-branding work that preceded public release was possible because the methodology-specific wording lived in templates, not in function bodies.
• A consistency-guard test — one that parses its own export and asserts the parsed value equals what the source computed — is worth writing. The QBR deck's commit figure is verified this way: the test builds the deck, extracts the number from the .pptx, and asserts it matches the forecast function's output. The two tools share the same core functions and the test proves it mechanically.
• The week-over-week delta algorithm needed explicit demotion paths for ambiguous cases: duplicate opportunity IDs fall back to name-join, duplicate name keys fall to unmatched. The alternative — picking one and moving on — produces a miscounted forecast that looks correct.

Mechanical invariant enforcement over advisory policies: if a requirement matters enough to write down, it matters enough to fail the process when violated. And the config-not-code pattern: behavior that might need tuning, substitution, or localization belongs in data files read at call time, not in function bodies that require a code change.

Case study in progress.