Build & Defend Newsletter 27

One email a week - something from which I hope you'll get real value. We talk about things we can build, and how to defend them. That can apply to cybersecurity, physical buildings, digital products, and .... just about anything. It gives me a lot of latitude in what I can write about, but the two concepts are important for progress - as individuals, and as society.

Today's topic is: dashboards for truth.

Everyone suggests that you need a dashboard for something, and with the advent of AI, it's easier than ever to do. I recently released an image viewer that I've made - PicturesQ (pronounced "Picturesque") and I'm curious as to how it's actually doing. (I used to use an image viewer called "Xee3" but it was purchased by the people that make "The Unarchiver" and I confirmed with them they have no plans to update Xee3 in the future.)

The difficulty I ran into was that when working with a dashboard, you can look at website visits. You can look at download-button clicks. You can look at the number of installers downloaded. You can look at purchases. You can look at refunds. You can look at people writing to you. You can look at a nice comment on Reddit and decide you are obviously about to be rich. But is any of that worthwhile? Does it require being combined in some fashion? If so, what, and how?

A visitor is not a customer. A click is not a download. A download is not an active user. A checkout page is not a sale. And a sale is not necessarily revenue you get to keep.

So I built a small dashboard that pulls together the things that matter, once a day, and gives me a boring answer. Boring answers are often the best answers.

🔨 BUILD: Your Dashboard

The dashboard is deliberately simple. It combines three sources: website analytics, github release downloads, and Stripe reports based on sales and refunds.

For PicturesQ, it answers these questions:

How many people visited the site?
Where did they come from?
Did they click a download button?
Which platform did they want: Mac, Windows, or Linux? (It's available for many platforms you see.)
Did anyone actually download an installer?
Did anyone start a checkout?
Did anyone pay?
Was anything refunded?

Plausible: Website Analytics

The website uses privacy-respecting analytics from Plausible for visits, page views, referral sources, campaign links, and download-button clicks. That tells me whether someone was interested enough to look at PicturesQ, and whether they tried to download it. It does not tell me whether they installed it. It definitely does not tell me whether they became a happy customer. A button click is intent. Useful, but not proof.

Github: Installer Downloads

PicturesQ installers are published as GitHub Release assets. GitHub provides download counters for each asset. That lets the dashboard see whether the Mac .dmg, Windows .exe or .msi, Linux .AppImage, .deb, or .rpm files were actually downloaded. GitHub’s number is cumulative, so the dashboard records a daily snapshot and calculates the difference. So I can see the difference from day to day.

Stripe: Money for Nothing and Your Clicks for Free

Well, of course it's not money for nothing, but I couldn't very well make the Dire Straits pun then could I? 😉

Stripe is the source of truth for sales. The dashboard checks completed, paid checkout sessions for the PicturesQ payment links, then reports:

paid orders
gross sales
refunds
refunded amount

That matters because a “thank you” page in a browser is not a reliable financial record. Pages fail to load. People close tabs. Ad blockers interfere. (I'm okay with that, but still need information.) Someone can refresh a page. A payment processor, on the other hand, knows whether or not it was paid.

The Report: The Information

Every day I get a daily briefing from my agent, Argent. (Yes, that's his name.) He includes the report on how things are going with PicturesQ, in a format that looks like this:

Traffic
7 days: visitors / pageviews
30 days: visitors / pageviews

Funnel
Download Mac
Download Windows EXE
Download Windows MSI
Download Linux AppImage
Download Linux DEB
Download Linux RPM
Premium Checkout
Premium Purchase

Stripe
Paid orders
Gross sales
Refunds

GitHub Releases
All installer downloads
Change since prior snapshot

That’s it!

You do not need a wall of colourful charts before you have enough real activity to justify one. You need a report that helps you decide what to do next. Besides, if it's just you, no one else will know or care if you have the fancy polar diagrams or not. (Fun fact: polar diagrams were invented by Florence Nightingale.)

Right now, PicturesQ’s dashboard is telling me that the only person who has visited the site is me. I'm working on changing that. It tells me that I need more attributable traffic and better distribution - not that I should congratulate myself for having a website.

🛡️ DEFEND: The Truth

There are two ways dashboards go wrong. The first is that they tell you flattering lies. (We're definitely trying to avoid those. I much prefer flattering truths!) The second is that they learn far too much about your customers.

It is very easy to turn weak signals into a good story:

“We had 100 downloads.” No, you had 100 download-button clicks.
“We have lots of interest.” Maybe. Or one person refreshed the page a few times.
“Checkout is working.” Someone reached the checkout page. That is different from paying.
“This campaign converted.” Did it produce a purchase, or just a few curious visitors?

The defence is to keep the stages separate. Each step leaks. That is normal. The point is to see where it leaks rather than inventing a conversion rate from mismatched numbers.

Defend Your Customers

PicturesQ is local-first software. People will hopefully use it to work through folders full of images, metadata, and even AI-generated assets. (I'm aware of the AI-working-through-AI-generated loop that may engender.)

I do not need to know anything about what they're working on: their image filenames, their prompts, their EXIF data, their folders, or how long they spent examining a particular photograph in order to know whether the product business is functioning.

The dashboard measures the business, not the customer’s private library.

That is a useful constraint. It means I need to be more careful about what I count. But I would rather have slightly less convenient information than build a hidden surveillance system into software that is supposed to respect its users.

Defend the Dashboard

Analytics keys and payment credentials are useful to attackers too. So the collector runs in GitHub Actions with its credentials stored as protected secrets - not in the code, not in the repository, and not in a screenshot somebody eventually posts to a support forum.

The revenue reports remain private. They are not deployed with the public website. Website visitors do not need to know my sales numbers, and I do not need to accidentally publish them because I wanted to update a headline.

Boring separation again. Boring separation remains one of the best security tools available.

💰 STACK: Small Tools, Clear Jobs

You could build this with plenty of different services. My current stack is:

Plausible (Business Subscription) - that gives me website traffic, referrers, campaigns, and download-button events

Github* Releases - actual installer asset download counters

Github* Actions - a daily scheduled run (note that this is not free)

Github* Action Secrets - no, it's not a Saturday morning cartoon, but protect storage for analytics and payment API credentials

Stripe - orders, sales, and refunds

Python - a small collector - made by Argent - that normalises the data and writes the report

Markdown & JSON - because a useful dashboard doesn't need to be a full-blown SaaS and it can just be text if needed

If you sell software, a course, a template, a physical product, or even a newsletter subscription, the same principle applies: measure each part of the system from the part that is best to see it and combine the information into a simple and meaning full report.

* Of note: I prefer to use Gitlab where possible (as Github is owned by Microsoft) but the functions I'm currently using are not available in Gitlab yet.