READ ME FIRST

You have just come across this project and you're wondering what it is, whether it's for you, and what to do with it. This document answers those questions in plain language — no technical knowledge assumed. Read it top to bottom once; it takes about ten minutes.

---

1. Who this is for

This is for people who raise money for a non-profit organisation: the development director, the gift administrator who processes the day's cheques, the annual fund manager planning the next mailing, the major gift officer about to pick up the phone.

It is built for small-to-mid-size non-profits — organisations that need a proper donor database but find the big commercial systems too expensive or too complicated, and the cheap ones too dated.

You do not need to be technical to use it day to day. Someone technical (a staff member, a volunteer, or a helper from the wbsp.ai community — see "Getting help" below) sets it up once; after that, everything a fundraiser does happens in an ordinary web browser.

Your donors never see the inside of this system. The only thing they ever see is a clean online donation form.

2. What it does

In a few plain sentences:

It keeps one record for every person, household, and organisation that supports you — their details, their history, every gift they've ever made. It records donations properly, the way your auditor and your board expect. It thanks every donor and sends their tax receipt automatically, minutes after the gift arrives. It runs your online donation page so supporters can give by card or bank transfer without any staff involvement. And it answers the questions leadership always asks — how are we doing, who has stopped giving, who should we ask next — from the same numbers, so you can defend every figure.

It runs on computers you control, so your donor list belongs to you. Nobody charges you per donor, and nobody else can see your data.

3. The world it lives in (a quick orientation)

If you're new to fundraising administration, here's the setting this system is designed for:

• Donors (called constituents in the system) are the people, households, companies, and foundations who give to you. Good fundraising depends on knowing them well — their history, their relationships, how they prefer to be contacted.
• Gifts are donations. Some arrive as cheques you enter by hand, some arrive online. Every gift goes to a fund (a pot of money with a purpose — General, Scholarship, Building), and may be credited to a campaign (a push toward a goal, like the Annual Fund) and an appeal (one specific ask, like the spring mailing).
• Pledges are promises to give later — "$1,200, paid monthly over a year." You need to track what's been paid and what's still outstanding.
• Recurring gifts are ongoing commitments — "give $50 every month, automatically." They're the most reliable revenue a non-profit has.
• Tax receipts are a legal obligation: donors need written proof of their gifts to claim deductions, and gifts of $250 or more require specific legal wording. Getting this right by hand is tedious; the system does it for every gift.
• Retention is the central worry of every development office: donors who gave last year but haven't this year are quietly slipping away. Finding and winning them back is where a donor database pays for itself.

This system exists to make all of the above routine, accurate, and fast.

4. Where it fits

Who uses it. Two kinds of people touch the system:

• Your staff — the development team, working in it for hours a day.
• Your supporters — who only ever see the public donation form, which you publish on your own website.

Systems it works alongside. The system doesn't try to do everything itself. It connects to:

• A payment processor (Stripe) — handles card, bank-transfer, and digital-wallet payments on the donation form and for recurring gifts. Card details go straight to the processor and never touch the system itself, which keeps you on the right side of payment-security rules.
• An email service — sends the thank-you letters and tax receipts. Until you connect a real email account, messages are written to a log instead, so nothing breaks while you're trying things out.
• Your organisation's sign-on — staff log in the same way they log in to the organisation's other systems. There is no separate password for this system, and nobody gets asked to sign in twice.
• Your other tools — everything in the system can be reached by other software through a documented, permission-controlled connection (an "API"), so an accountant's export or a mailing house's sync can be automated when you need it.

5. First run — the very first thing to do

If you just want to see what this is, there's a self-contained preview: one package that runs the whole system on your own machine, already loaded with a realistic two-year demo dataset, so every screen has something to show.

Ask whoever is helping you technically to start the preview (it runs in a container and appears at an address like http://localhost:4000 — full instructions are in preview/README.md, and starting it takes about a minute the first time while the demo data loads).

Then, in your browser:

1. Open the donation page first — it works without signing in, and it's the one thing your donors will ever see. Make a test gift.
2. Sign in to the staff side using your organisation's platform account (the same sign-in you use elsewhere — there's no separate password for this system).
3. Land on the dashboard and click around: search for a donor, open their record, look at a campaign's progress, run a report. Everything is safe to explore — it's demo data, and it resets itself every time the preview restarts.

That fifteen minutes tells you more about the system than any document.

6. Setting up for real

When you move from "looking" to "using", the setup happens in this order:

1. Start with a clean system. For a real deployment, the technical operator runs an initialisation step that wipes everything and loads only the bare minimum: your organisation's name and the first administrator's sign-in identity. Nothing fictional, nothing to clean up. (This step is deliberately guarded — it asks for typed confirmation before deleting anything. The details are in user-docs/production-init.md.)
2. Sign in as the first administrator and fill in the organisation settings. Do this before anything else: your legal name, tax ID, and address appear on every tax receipt.
3. Create your staff — each person signs in with the organisation's normal sign-on, and the administrator assigns their role (see "Who can do what" below).
4. Create your structure — the funds, campaigns, and appeals that match how your organisation actually raises money.
5. Connect the outside world — the payment processor for online giving, and the email service so receipts really reach donors. (Both can wait; the system works fully without them while you're evaluating.)
6. Bring in your existing data. Export your current donor list (and gift history) to spreadsheet files, then use the built-in import: you match your columns to the system's fields, it spots likely duplicates and holds anything uncertain in a review queue for a human to decide, and — crucially — every import can be completely undone if it goes wrong. Importing your gift history means your lifetime-giving totals and lapsed-donor lists are correct from day one.
7. Publish your donation form. Set your branding, suggested amounts, and default fund — no programming — and put the form on your website.

7. Day to day

A normal working day in the system looks like this:

Morning — the dashboard. Open it and see, at a glance: how giving is going, your donor retention rate, your lapsed-donor counts, average gift size, and progress toward each campaign goal. Every number comes straight from the gift records — when the board asks where a figure came from, the answer is always "the gifts themselves."

Processing the mail — gift entry. The day's cheques go in as a batch, like a bank deposit slip: you state up front how many gifts you have and what they add up to, then enter each one — who gave it, how much, which fund. Special cases are one click each: a cheque covering two purposes splits across funds (the parts must add up to the whole); a board member who influenced the gift gets a soft credit (recognition, not money); an in-memory-of gift is marked as a tribute; an anonymous donor is kept off public honour rolls with one checkbox. When you close the batch, if what you entered doesn't match your stated totals, the batch refuses to close. That's the system protecting you, not fighting you — it's catching a typo today instead of a reconciliation nightmare in December.

Answering the phone — donor lookup. Type part of a name or email into search; the right person is almost always on the first page. Their record shows everything in one place: contact details, household, relationships, addresses, and a timeline of every touch — gifts, pledges, receipts, notes. A consents panel shows what they've agreed to receive, so you never call someone who asked you not to.

Chasing promises — pledges. The pledge list shows who promised what, what they've paid, and what's outstanding — who might need a gentle reminder.

Monthly givers — no work at all. Recurring donors are charged automatically on schedule; each charge becomes a properly recorded, receipted gift. If a card fails, the system retries on its own schedule and only bothers you — with a flag and an alert — when it keeps failing, so a human can reach out.

Planning the next ask — segments and reports. Build a group of donors by rules ("gave $100+ last year, nothing this year, in these ZIP codes"), save it, preview exactly who's in it, and export the list for your mailing house or email tool. The standard reports — lapsed-donor lists, top donors, retention trends, campaign comparisons — run in seconds.

Online gifts — they handle themselves. When someone gives on your website, the system recognises existing donors instead of creating duplicates (and asks you, via a review queue, when it's unsure), records the gift to the right fund, and sends the confirmation and tax receipt — all before you've finished your coffee.

8. Ongoing care

• January: year-end tax summaries. Generate every donor's annual statement in one batch — one document per donor listing all their gifts and the deductible total.
• Every gift, forever: receipts. Re-issue any receipt any time; the new copy gets a new number and the old one is marked superseded, never deleted. If a gift is voided or refunded (an Admin-only action), its receipt is marked void — the paper trail stays intact for your auditor.
• Housekeeping: duplicates. When you find two records for the same person, merge them: all gifts, addresses, and relationships move to the surviving record, and the merge is written to the audit log.
• Privacy requests. If a donor asks for a copy of their data, or asks to be forgotten, Admins can run an export or erasure; gift records the law requires you to keep for financial audit are preserved in anonymised form. Per-donor communication consents are enforced automatically before anything is sent.
• Backups. The system's data lives in a single database under your control. Your technical operator should back it up regularly (the preview container is not a place to keep real data — it resets to the demo state on every restart).
• Audit trail. Every change made through the system is recorded, so you can always answer "who changed this, and when?"

---

A short glossary

Terms you'll meet in the system and its documents:

• Appeal — one specific ask within a campaign, e.g. the spring mailing or the year-end email.
• Batch — a group of gifts entered together with a stated count and total, like a bank deposit slip; it can't be closed until the entries match the stated totals.
• Campaign — a fundraising push with a goal and a date range, e.g. the Annual Fund.
• Constituent — anyone in your database: an individual donor, a household, or an organisation.
• Fund — a pot of money with a purpose (General, Scholarship), which every gift must be assigned to; it also records whether the money carries donor-imposed restrictions.
• LYBUNT / SYBUNT — fundraising shorthand for donors who gave Last Year / Some year But Unfortunately Not This year — your win-back lists.
• Pledge — a promise to give, usually paid in instalments over time.
• Recurring gift / sustainer — an ongoing automatic donation, e.g. $50 charged monthly.
• Restriction class — the accounting label (per the FASB ASC 958 rules) saying whether a gift may be used freely or only for a donor-specified purpose. Every gift carries one.
• Segment — a saved group of donors defined by rules, used for mailing lists and reports.
• Soft credit — recognition of someone who influenced a gift but didn't give it (e.g. the board member who asked); it never affects the money totals.
• Tribute — a gift made in honour or in memory of someone.
• Tax receipt — the legally required written acknowledgment of a gift; gifts of $250 or more require specific IRS wording, which the system includes automatically.

Who can do what: the two roles

Every staff member has one of two roles:

• Staff — all the daily work: donors, gifts, batches, pledges, campaigns, segments, reports, receipts.
• Admin — everything Staff can do, plus the sensitive operations: managing users, running data imports, voiding or refunding gifts, and changing system settings.

Demo data and starting fresh

• The preview ships fully populated: staff users, funds, campaigns and appeals, households and donors with addresses, organisations, two years of gifts (with splits, soft credits, and a pledge), a gift batch, recurring donations, receipts, a saved segment, a published donation form, and more — so every screen demonstrates something. It's safe to re-run the seed; it never creates duplicates. Details: user-docs/demo-data.md.
• To start fresh for a real deployment, use the initialisation procedure in user-docs/production-init.md. It wipes the database and loads only your organisation's settings and the first administrator — deliberately, with strong typed-confirmation safeguards, because it is destructive. Never run it against a database you care about.

The other documents in this folder

Document	What it's for
READ-ME-FIRST.md	This document — orientation for a first-time reader.
demo-data.md	How to load (or re-load) the fictional demo dataset, per environment.
production-init.md	How to initialise a fresh stage/production system safely — the destructive, guarded reset-to-clean procedure.
store-thumbnail.png	The thumbnail image used for this project on the wbsp.ai store/community listing. Not a how-to document.

Further reading elsewhere in the project, once you're oriented:

• collateral/user-guide/getting-started-plain-english.md — a hands-on "five things you'll do most" guide for staff.
• collateral/user-guide/user-guide-detailed.md — the exhaustive reference: every screen, field, and rule.
• preview/README.md — how to run the self-contained preview (for your technical helper).
• docs/walkthrough-screenshots/script.md — a narrated screen-by-screen tour of the interface, with screenshots.

FAQ and common gotchas

Is there a password for this system? No. Staff sign in through the organisation's normal sign-on; there's no separate login to remember (and in the preview, the donation page needs no sign-in at all).

My batch won't close. Is it broken? No — the totals you typed don't match the gifts you entered. Recount the pile of cheques, find the typo, and it will close. This check is the single best protection your gift ledger has.

A donor gave online and now appears twice. The system matches online gifts to existing donors automatically and holds uncertain matches in a review queue rather than guessing. If a duplicate does slip through, merge the two records (an everyday Admin/Staff operation, fully audit-logged).

Where are my thank-you emails? Until a real email service is connected, outgoing messages are written to a log instead of being sent — by design, so you can try everything without configuring anything. Connect the email service before go-live.

The preview forgot my changes! Expected: the preview reloads the demo data every time it starts. It's for looking, not for keeping. Real deployments don't behave this way.

Can I use it in two currencies? Not in this version — one operating currency per deployment, chosen at setup (default US dollars).

Does this version include the AI features the project description mentions — donor scoring, ask recommendations, planned giving, grants management? Not yet. This version is the deliberately solid core: donors, gifts, campaigns, online giving, receipts, segments, reports, and import. The AI-scoring layer, planned giving, grants management, and wealth-screening integrations are planned for later versions; the data model leaves room for them, so adding them won't require starting over.

Getting help

This project is part of the wbsp.ai community — the "world's biggest software project" — where this application was built by AI and where many versions and variations of it (and other applications) live. Visit https://wbsp.ai to:

• ask questions and make suggestions,
• find people who can install, customise, or brand the system for you,
• see other community-built versions — one of them may already be a perfect fit.