WHAT IT IS
Four local tools that turn a weekly CRM export into a seller's reports.
Seller Admin Tools is four small tools that run locally on the weekly pipeline CSV a CRM exports. The first imports the file and maps its columns, and the other three turn it into a forecast narrative, a QBR (quarterly business review) deck and an account plan. The narrative and the deck share the same forecast math, which totals deals by forecast category: commit for the deals a seller expects to close this period, then upside and pipeline for the less certain ones. None of the tools writes back to the CRM, and they are deterministic, meaning the same imported file always produces the same output.

WHAT CHANGED
Links to outside servers were switched off and checked at startup.
The tools were built on Streamlit, a Python library for simple web apps, then ported to FastHTML, a Python web framework. The port plan found that FastHTML's fast_app() setup loads five assets from a CDN (an outside server that hosts scripts and styles) by default, two under a moving label like @latest, so the code a browser loaded could change with no edit to the app. The port switched those off, served local copies, and added a check that stops the app at startup if a script or style link it adds points to an outside server. That check reads only those links, and a test that blocks network connections while writing a forecast narrative covers that one path.
CONTROL
The QBR deck and the forecast narrative must report the same commit figure.
Both documents report the commit total, so a test builds the QBR deck, reads the commit figure back out of the PowerPoint file and fails if it differs from the narrative's figure. Each tool's exports also have golden-file tests, which compare a fresh export with a saved known-good copy: markdown exports must match byte for byte, and the QBR deck is compared by its parsed content, since a .pptx file is not byte-for-byte the same from one build to the next.
LESSONS
Two patterns from this build.
- Put an ambiguous match in a count the reader can see instead of letting the code pick one. The week-over-week comparison pairs this week's deals with last week's by opportunity ID, then by account and deal name, and the first version could pair duplicates silently. Two fix commits changed that: a duplicate ID now falls back to the name match, and a duplicate name lands in an explicit unmatched count.
- Keep wording you expect to change in config files, and still search the code when it changes, since some of it spreads. Stage labels, risk thresholds and narrative templates sit in YAML files (plain-text settings) read at run time. Replacing the original terminology before public release edited the stage-label file and also a QBR page file, the docs, the tests, a sample CSV and the demo seed script.
PROJECT DESIGN
How it works.
How data moves
Key modules
Ingest / Mapping
CSV parsing with date-format resolution (auto/US/International/ISO with live preview), a money parser that handles dollar signs, thousands separators, and parenthesized negatives, and five validation states (blocking vs. warning — rows still import on warnings). Auto-suggests column mapping against PIPELINE_SCHEMA and ACCOUNT_SCHEMA; the user confirms every field, suggestions are never applied silently. Named profiles make re-import zero-click. Re-import detection keyed by file SHA-256 catches the same file submitted twice.
Forecast Narrative
Commit / upside / pipeline bucket rollup using forecast_category when present, stage-derived otherwise. Week-over-week delta runs in two passes: ID-join first on opportunity_id, name-join fallback for ID-less rows. Duplicate non-empty IDs are demoted to name-join; duplicate name keys are demoted to unmatched — every ambiguous case is surfaced, never silently miscounted. Four risk flags (stalled: 45 days; slipped: 90 days; no_sponsor: deals ≥$500K; big_and_late: deals ≥$1M closing within 30 days), each with a plain-English evidence string and a configurable coaching ask from risk_rules.yaml. Exports to .md.
QBR Assembler
One-click from snapshot to a five-slide .pptx deck (title, scorecard, native bar chart, top deals, risks and asks) plus a .md appendix. Per-seller rollup with alias normalization across snapshots. A consistency-guard test parses the commit figure back out of the built deck and asserts it equals the narrative's — the two tools share the same core/forecast functions and cannot drift. DRAFT footer on every slide; tables row- and column-capped; long names truncated.
Account Plan
Joins an account-facts CSV with open pipeline. Obligation → capability → gap crosswalk: each obligation is marked landed, partial (a competitor holds it), or gap. Whitespace estimate sums open pipeline against gap capabilities; products that cannot be resolved to a capability are excluded and reported rather than guessed. Rule-based next actions. Exports to .pptx and .md.
Config layer
Six YAML files in config/ drive all behavior at call time: stage_map.yaml (raw CRM stage string → canonical bucket), aliases.yaml (account and owner name normalization), risk_rules.yaml (four flag thresholds and coaching asks), narrative_templates.yaml (sentence templates for forecast output), obligation_map.yaml (regulatory obligation → required capability), product_map.yaml (product name → capability category). No code change needed for new CRM formats, thresholds, stage labels, or regulatory frameworks.
Security layer
Pure-ASGI LocalOnlyMiddleware (web/security.py) rejects requests with non-loopback Host headers and blocks CSRF by requiring a same-origin Origin or Referer header on all mutating requests. Startup assert checks the configured head tags at import and raises RuntimeError if any src or href points to an external URL. Dependency floors in constraints.txt. Security-audit CI on pushes to main, pull requests and a weekly cron.
SECURITY & OPERATIONS
Security and operations.
- 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 checks the configured head tags when the server module loads and raises RuntimeError if any src= or href= value contains an external URL, so a CDN reference added to those tags stops the server from starting.
- 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 in the narrative 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 pushes to main, pull requests, and a 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.
BUILDER NOTES
Builder notes.
- The Streamlit-to-FastHTML migration came after the four feature sessions had built the tools on Streamlit. LocalOnlyMiddleware landed while the port was still in progress, from a commit that credits a security review of the tool, and was written to work with the port.
- 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.
WRITING
Field notes from this work.
No public field notes for this project yet.
Full build narrative
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 with FastHTML's default CDN assets turned off, and a commit from a security review of the tool added a local-only network guard. 73 commits · 10 PRs · 4 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/, which call the same core functions the exports call, so on-screen numbers and exports 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 move from Streamlit to FastHTML ran through two of those ten pull requests.