Read Me First

A plain-language orientation for anyone meeting this project for the first time. No technical background assumed — if you work in finance, operations, or customer support at a company that sells subscriptions, this document is written for you.

---

1. Who this is for

This project serves two groups of people at a company that sells subscriptions (the "operating company"):

• Billing administrators and finance staff — the people who define what the company sells, at what price, who watch the money coming in, chase failed payments, and close the books at the end of each period. They work in the admin console.
• The company's own customers — the people who buy the subscriptions. They use a self-service portal to check their plan, see their usage, look at past invoices, update their card, or switch plans — without emailing support.

There is also a third audience worth naming: companies that adopt this project as the foundation of their own product. The software is deliberately plain and unbranded so another business can put its own name, colours, and logo on it. If that is you, everything in this document still applies — you are evaluating the engine before you repaint the car.

2. What it does

In a few sentences: this is a complete billing system for companies that charge customers on a recurring basis. It keeps the catalogue of products and prices, tracks who is subscribed to what, counts how much each customer uses (for pay-per-use pricing), produces correct invoices at the end of every billing cycle, collects payment by card, automatically retries and follows up when a payment fails, and prepares the revenue figures finance needs for the official accounts. It also records — permanently — everything that ever happened, so any number on any screen can be traced back to its origin.

3. The domain

Many modern businesses do not sell a product once; they sell ongoing access. A software company might charge a flat monthly fee, a fee per team member, a fee that rises in tiers as usage grows, or a mixture of all three. Some customers pay monthly, some annually, some start with a free trial. That sounds simple until you meet the day-to-day reality:

• A customer upgrades halfway through the month and is owed a credit for the unused days of the old plan and a charge for the remaining days of the new one — to the cent.
• A card expires, a payment fails, and someone has to retry it and nudge the customer — politely, repeatedly, and without a human watching every case.
• The tax authorities and the accounting standards require that revenue from an annual prepayment is recognised month by month as the service is delivered, not all at once — and an auditor may ask you to prove any figure years later.

The commercial products that do this well are expensive (enterprise suites cost tens to hundreds of thousands per year, or take a percentage of every dollar billed). This project is an open, self-hostable alternative: a billing foundation a company can run itself and make its own.

4. Where it fits

This software sits between three worlds:

• Your own product. Your application reports how much each customer used (for example, how many requests they made or minutes they consumed), and reads back subscription status so it knows who is entitled to what.
• The outside money systems. Card payments are handled by a payment provider — by default Stripe, in its safe test mode, so no real money moves during evaluation. Real card details never touch this system; they stay with the payment provider. Tax calculation and email delivery are also deliberately left to outside services: out of the box, tax is zero and emails are only logged, so the system runs with no vendor accounts at all, and a real tax or email service can be connected later.
• Your company's sign-in. Staff log in through a shared single-sign-on service (the same one the preview is wired to), and the company's customers have their own separate accounts there for the portal. Who may do what is controlled by roles — see the roles section below.

One deployment of this software serves one company. It is not a multi-tenant service hosting many businesses at once.

5. First run

The easiest way to see the product is the preview: a single ready-made package that runs the entire system on your own computer with realistic demo data already loaded — no setup, no external accounts. Ask whoever gave you this project to run it, or follow the short instructions in preview/README.md (a plain Docker run; it needs only Docker installed).

Once it starts (allow about a minute on first launch), three doors open on your machine:

• The admin console — the staff back office. This is where you should go first. Sign in through the shared test sign-in service it redirects you to, and you land on a dashboard of a fictional software company already billing its customers.
• The customer portal — what the company's customers see. Try it after the admin console to experience the other side of the counter.
• The API — the machine interface other systems use; not something you need on a first look.

A hosted sandbox demo is also published on wbsp.ai ("Try in sandbox") if you would rather click than install.

Your first five minutes: sign in to the admin console, open the Invoices section, click any invoice, and look at how every line — plan fee, usage, discount, mid-cycle adjustment — adds up to the total. That one screen is the heart of the product.

6. Setting up

How far you go depends on why you are here:

• Just looking? You are already done — the preview above is the complete working environment, preloaded with demo data.
• Evaluating seriously? Still use the preview, but walk a full cycle: create a product and a plan in the catalogue, add a customer, start a subscription, then look at the invoice it produces. The demo data means you can also explore dunning, credits, and revenue reports without building anything first.
• Adopting it for real? The real setup work is connecting the outside pieces this core deliberately leaves pluggable: your live payment-provider account, your tax service, your email service, and your company's sign-in for staff. You will also re-skin the two web apps with your own branding — the product ships plain on purpose. The deployment guide (docs/deployment.md) and the production-initialization note under user-docs/ cover the operational side; both are written for the technical colleague who will do that work with you.

7. Day to day

Life in the admin console is organised into eight sections:

• Dashboard (the home page) — the morning glance: what came in, what failed, what needs attention.
• Catalog — what you sell: products, plans, prices, and coupons. This is where a pricing change starts.
• Customers — who you bill: their details, currencies, and payment methods on file.
• Subscriptions — who has what: start, pause, upgrade, or cancel a subscription. Mid-cycle changes are worked out for you, and the adjustment appears on an invoice immediately, explained line by line.
• Invoices — the statements: every cycle's charges, in every state from draft to paid to past due. This is where you issue a credit note when a refund is due.
• Payments — the collection attempts behind the invoices: what succeeded, what failed, what was refunded.
• Dunning — the automatic recovery of failed payments: the retry schedule, the reminders, and which cases recovered, are still working, or gave up. Normally it runs itself; you come here to check progress or tune the schedule.
• Revenue — the finance view: how billed money is recognised over time for the accounts, with the reports you need at period end.

A typical day: check the dashboard, clear anything in dunning that needs a human touch, answer a customer question by opening their record and reading the exact figures they see. A typical week: add or adjust plans, review the payments that failed. Meanwhile, your customers mostly never contact you — they serve themselves in the portal: view plan and current usage, download invoices, replace an expiring card, or change plans (which takes effect immediately, with the adjustment handled for them).

8. Ongoing care

• Each period end, finance produces the revenue-recognition report from the Revenue section — designed to be a minutes-long task, with every figure traceable back to its source.
• Routinely, review dunning: confirm failed payments are recovering and step in on the few that exhaust their retries.
• Continuously and automatically, the system keeps a permanent, tamper-evident record of everything — every invoice, payment, price change, and staff action — so audits and "why is this number what it is?" questions always have an answer. That record is append-only by design and cannot be edited after the fact.
• Operationally, the data lives in a database your organisation runs, so the usual rule applies: make sure someone owns regular database backups. In the preview, deleting the container deletes the demo data with it — fine for a look around, worth knowing before you invest time customising it.

---

Glossary

• Subscription — an ongoing agreement: this customer gets this plan and is billed for it every month (or year) until cancelled.
• Plan — a priced offering: what is included and what it costs (flat fee, per seat, per amount used, or a mix).
• Usage metering — counting what each customer consumes (requests, minutes, seats) so pay-per-use pricing has numbers to work from.
• Invoice — the per-period statement adding up plan fees, usage, discounts, and adjustments.
• Proration — the fair split when a plan changes mid-period: credit the unused days of the old plan, charge the remaining days of the new one.
• Dunning — the polite, automatic chase when a payment fails: retry the card, remind the customer, try again, and only then give up.
• Credit note — the corrective document issued when money must go back to a customer, linked to the original invoice.
• Revenue recognition — the accounting rule that prepaid money counts as revenue gradually, as the service is delivered, not all on day one.
• Credit wallet — a prepaid balance a customer draws down against invoices before any card is charged.
• Commit contract — an agreement to spend a minimum amount over a term, with a top-up invoice if usage falls short.
• Audit trail — the permanent, uneditable log of everything that happened and who did it.

The other documents in this folder

• demo-data.md — exactly what fictional demo data ships with the product and how to load it into a demo environment (24 customers, subscriptions in every state, invoices, payments, dunning cases, revenue schedules, and more).
• production-initialization.md — how to prepare a real environment for first use: wipe to a clean slate and load only the minimal starting data. It is guarded by multiple safety confirmations so it cannot be run by accident.
• login-bypass.md — a convenience for automated testing and screenshot/video recording on a local machine only: a way to skip the sign-in screen. It can never activate on any real or cloud deployment.
• store-thumbnail.png — an image for marketplace/store listings; not documentation.

Who can do what (roles)

Staff access is controlled by four roles, assigned in the company's sign-in service:

• Billing admin — full control: catalogue, pricing, customers, subscriptions, settings.
• Finance — the money side: invoices, payments, credit notes, revenue reports, dunning oversight.
• Support — helping customers: viewing records and performing customer-service actions, without the ability to reshape pricing or finance configuration.
• Read — look but do not touch: view everything, change nothing.

Customers, separately, can only ever see and manage their own account in the portal — never anyone else's, and never the admin console.

Demo data and starting fresh

The preview ships loaded with a fictional software vendor billing 24 demo customers: subscriptions in every state (trial, active, paused, cancelled), invoices from draft through paid to past due, successful and failed payments, credit notes, dunning cases in progress, prepaid credit balances, and revenue-recognition schedules — all using made-up names and .example addresses, so no real person's data is involved. The full inventory is in demo-data.md.

To start fresh — for example to rehearse a real rollout — the production-initialization routine wipes the environment back to a clean, minimal starting state (one sensible default dunning schedule and one bootstrap access key; nothing else). It is described in production-initialization.md and is deliberately hard to run by accident. The demo seed and the production reset are opposites: one fills the system with fiction for evaluation, the other empties it for real use — never mix them up.

Common questions and gotchas

• "Where do I log in?" The preview redirects you to a shared test sign-in service — that is expected; it is how staff sign-in works in this project family. A real deployment uses the adopting company's own sign-in.
• "Did that payment actually charge a card?" No. Payments run against the payment provider's test mode by default; no real money moves.
• "My invoice shows zero tax." Correct out of the box — tax is a stub until a real tax service is connected.
• "The customer never got the invoice email." Also expected — email is only logged, not sent, until a real email service is connected.
• "I changed a price and existing customers kept the old one." That is a feature: existing subscribers keep their agreed pricing unless you explicitly migrate them.
• "I deleted the preview container and my changes vanished." Expected — the preview is disposable by default; preview/README.md shows how to keep data across restarts if you want to.
• "Can it host several companies at once?" No — one deployment serves one company, by design.
• "The branding isn't ours." Intentional — the product ships plain so adopters can apply their own identity.

Where to get help

Questions, feedback, and discussion live with the project's community at wbsp.ai — where you will also find the hosted sandbox demo of this product ("Try in sandbox"). For anything in this document that turns out to be unclear or wrong, the community is the right place to say so.