Help guide

🚀 Getting started

On your very first visit to a fresh installation, the sign-in page asks you to create the administrator account — do this straight away, because until then anyone visiting the site could claim it. After that, the same page is the normal sign-in.

The three roles

• Admin — everything, including database structure, users, connections and settings.
• Editor — day-to-day work: records, fundraising, tasks, workflows.
• Read-only — can view and export everything, change nothing. Ideal for trustees.

Invite colleagues from Settings → Users → + Invite user. A one-time temporary password is generated — pass it on securely; they can change it after signing in with the 🔑 button at the bottom of the sidebar.

The 🌓 button in the sidebar footer switches between light and dark themes. The footer also shows the running version and start time — handy for checking a new deployment has landed.

🏠 Dashboard

The Home page is made of cards: metric cards (a count or sum, optionally filtered — e.g. "Donations this quarter"), list cards (recent records), and chart cards (any saved chart).

• Click ⚙ Customise to enter edit mode, then + Add card to add, or ✕ to remove a card.
• 🔁 Process recurring runs the daily housekeeping on demand: generates payments due on active regular gifts, lapses overdue memberships, and creates grant deadline/report reminder tasks. The same jobs also run automatically every time the server starts.

🗂️ Records, lists & fields

The whole CRM is built on one idea: everything is a record of a type. People, Payments, Events, Grant applications — all records. Each type has fields, and both types and fields are editable data, not code: change them in Settings and every list, form, filter, chart and API updates instantly.

Working with lists

• Search looks across every field of the type, as you type.
• ⚲ Filters builds AND/OR condition groups with operators that match each field's type (contains, is, greater than, before, is empty…).
• ☆ Save view stores the current search + filters + sort as a named pill above the list, per record type — one click to return to it.
• Click a column heading to sort; click a row to open the record.

The record page

Four tabs: Details (edit fields inline — changes save from the tick that appears), Relationships (what this record points at, and everything that points back at it — a person shows their payments, tasks, memberships and grants automatically), Attachments (files you've uploaded onto this record), and Timeline (activities, emails, payments and the full audit history in date order).

Attachments

The Attachments tab lets you keep files with the record they belong to — a signed grant agreement on the grant application, a scanned letter on a person, funder correspondence on an organisation. Click ⇧ Upload file, pick a file (up to 10 MB each), and it appears in the list with its size and who uploaded it. Click a file name to download it; use the 🗑 button to remove one. Every upload and removal is recorded in the record's Timeline. Read-only users can download files but not add or delete them. Files are stored on your server's data volume alongside the database — if you back up the database, back up the attachments folder next to it too.

Custom types and fields (admins)

In Settings, add fields to any type or create whole new record types. Field types include text, numbers, currency, dates, checkboxes, ratings, dropdowns (single or multi-choice), "point to another record" relationships (single or multiple), and user fields for assigning things to colleagues. Record naming is controlled by an editable title template like {first_name} {last_name}.

CSV import and export

• ⇩ Export CSV exports the current list respecting search and filters, with relationships resolved to names.
• ⇧ Import CSV matches columns to field labels or keys (case-insensitive). Multiple emails or multi-choice values go in one cell separated by semicolons: a@x.je; b@x.je.

Bulk update

Need to set the same value on lots of records at once? Search and filter the list down to exactly the records you want, then click ✎ Bulk update. Pick a field, choose the new value, and confirm — every record currently shown is updated in one go. Records that already hold that value are left alone, and each change is written to the record's history just like a normal edit. (Read-only users don't see the button.)

👤 People & organisations

People and Organisations are the heart of the database — nearly everything else links to them. Emails and phones are multi-value with a starred primary: add as many as you like and mark which one to use by default. A person can belong to several organisations, and can be more than one thing at once — Supporter type is multi-choice (Donor and Volunteer, say).

• ✉ Send email on a person's record sends a templated email (see Workflows & emails).
• 🔗 Portal link generates their secure self-service link (see Supporter portal).
• 🧹 Duplicates in the list header finds and merges duplicate entries (see Duplicates & merging).

💷 Payments & regular giving

A Payment is any money in: donation, membership fee, ticket sale, grant, legacy. It links to the person or organisation it came from, and optionally to a campaign, membership, subscription or grant application.

Subscriptions are Beacon-style regular giving: the subscription record is the agreement (amount, frequency, status, next payment date) and payments are the transactions. In demo mode a monthly gift is handled by the built-in scheduler, which creates each Payment record when it falls due and advances the next-payment date. When PayPal is switched on, a monthly gift becomes a PayPal subscription: PayPal charges the donor and each payment is recorded automatically, so the scheduler leaves those alone.

💚 Jersey Gift Support

Open Charity CRM implements Jersey Gift Support (not UK Gift Aid): single donations of £50 or more from Jersey-resident taxpayers earn the charity an extra 25p per £1, reclaimed from Revenue Jersey.

How it works, end to end

1. A donor makes a declaration and provides their tax identification number (TIN) — via your donation page, the supporter portal, or typed into their person record by you.
2. Every donation is checked automatically as it arrives or changes: type Donation, £50+, declared donor with a TIN.
3. Eligible donations accrue onto the current quarterly claim, visible on the 💚 Gift Support page with running totals and the 25% reclaim value.
4. When the quarter is ready, export the reclaim schedule CSV (donor, address, TIN, date, amount, reclaim) and send it to Revenue Jersey, then mark the claim Submitted — which locks its payments — and later Paid.

🏛️ Grant applications

Track the grants your charity applies for — trusts, foundations, public funds. Each application records the funder (an organisation) and your contact there, the amounts requested and awarded, the application deadline, submitted and decision dates, the next report due to the funder, and what the funding is for.

The pipeline

Grant applications open as a board: columns for Researching → Preparing → Submitted → Awarded / Declined → Completed, with each column showing its count and total money. Drag a card to move an application between stages; click it to open the full record. The ☰ button switches back to a normal list.

Never miss a deadline

When an application in Researching or Preparing has a deadline within 14 days, a reminder task is created automatically — once. The same happens for the report due date on Awarded grants. Reminders appear on the Tasks page linked to their grant. They're generated at server start and whenever you press 🔁 Process recurring.

Link the money

When an award arrives, record it as a Payment (or pull it in from Xero) and set its Grant application field — the grant record then shows exactly what was received against it, totalled.

🔗 Xero accounting sync

Entirely opt-in, set up from Settings → Connections. It needs a free Xero developer app and two environment variables on your server — the DEPLOY.md file in the repository walks through this once-only setup.

Pushing payments to Xero

After connecting, choose which Xero bank account payments post to and an income account code per payment type (custom payment types appear automatically). From then on payments sync as bank transactions — automatically at startup, on ↻ Sync now, or from a workflow action. The sync is idempotent (a payment is never posted twice) and never blocks payment creation if Xero is unreachable; a log on the Connections card shows every attempt.

Pulling money in from Xero

For money that landed in Xero without going through the CRM (a bank transfer entered by your bookkeeper), open Settings → Connections → Import donations from Xero: tick which Xero income accounts to pull from, press ↓ Pull from Xero, and review the staged transactions. Link each one to an existing donor — or create a new person/organisation on the spot — then press Import. Nothing is ever created without that explicit step, imported payments are excluded from outbound sync, and already-known transactions are filtered out automatically.

🪧 Public forms & giving pages

"Donation forms" records define your public pages — each has a web address like /give/spring-appeal that you can link from your website or share directly. Three form types:

• Donation — suggested amounts, optional monthly giving, campaign allocation, and a built-in Jersey Gift Support declaration with TIN capture. Donors are matched to existing people by email or created automatically.
• Membership — tiered prices ("Individual: 25, Family: 40, Life: 250"), automatic member numbers, and the joining payment recorded.
• Event registration — priced ticket types including multi-attendee tickets ("Table of 8: 250 x8"), live totals, and capacity enforcement with sold-out handling.

Every form record has an Active switch, and the record page shows an 🪧 Open public form button so you can see exactly what supporters see. Submissions from any form trigger workflows.

🎪 Events, tickets & memberships

• Events hold the date, location, capacity and campaign; each sale creates Ticket records linked to the buyer and payment, and capacity is enforced across all ticket types (a "Table of 8" counts as eight seats).
• Memberships record the type, status, member number and renewal date. Memberships past their renewal date lapse automatically. Life memberships never expire.

💚 Supporter portal

On any person's record, 🔗 Portal link generates a secure tokenised link to give them. Without needing an account, the supporter can update their contact details, make or update their Jersey Gift Support declaration and TIN (which re-runs eligibility on their donations), choose whether to receive emails (their email consent), and see their memberships, regular gifts and payment history. Changes they make are recorded in the record's history as "Supporter portal".

✅ Tasks

The Tasks page (top of the sidebar) shows every open task grouped Overdue / Today / Upcoming / No date, each with its due date, assignee and links to the related person, organisation or grant. Tick the checkbox to complete a task; recently completed ones sit struck-through at the bottom.

• + New task creates one pre-assigned to you — change the assignee to any colleague.
• Assigned to me filters the page to your own tasks.
• Tasks are Activity records under the hood, so they also appear on the timeline of whatever they're linked to, and workflows can create them automatically.

⫿⫿ Pipeline boards

Any record type with a dropdown field can be viewed as a drag-and-drop board: the ☰ / ⫿⫿ toggle appears in the list header, with a picker for which dropdown drives the columns. Cards show the record's name, money and date; columns show counts and currency totals. Dragging a card updates the field for real — including triggering any workflows that watch it. Search and filters still apply in board view.

Grant applications open on their pipeline by default; Payments by type, event check-in by status, and any custom status field you add all work the same way.

📊 Charts

Build charts from any record type at Reporting → Charts: choose bar, line or pie, whether to count records or sum a field, what to group by (a dropdown, checkbox, rating or date — dates bucket by day/week/month/quarter/year), and an optional filter condition. Charts preview live on the page, and any saved chart can be pinned to the Dashboard via Customise → + Add card → Chart.

Line charts need a date field to group by — a trend only means something over time.

⚡ Workflows & emails

Workflows automate the routine: when a record of a chosen type is created or updated, if it matches your filter conditions, then run actions:

• Create a record — e.g. a thank-you Task linked to the donor. Values support {field} merge tokens from the trigger and {today}.
• Update the triggering record — set a status, stamp a date.
• Send an email — from a template, with merge tokens.
• Sync to Xero — for payment workflows.

Workflow actions never trigger other workflows, so you can't create loops. Email templates live on the ✉️ Emails page along with the outbox.

Real delivery & email consent

When your administrator has connected an email provider (Postmark — see Deploying), emails are sent for real; otherwise they're logged in demo mode. The ✉️ Emails page tells you which mode you're in.

To respect Jersey data-protection rules, the app only delivers emails to people whose Email consent is “Opted in”. Anyone else — “Not asked” or “Opted out” — still gets the email logged to their timeline, but it is not sent. The send screen warns you before it does this. People can opt in themselves by ticking “keep me updated” on a donation form or in the supporter portal, and staff can set consent on a person's record. Every consent change is recorded in the person's history.

📄 Letters & mail merge

Generate Word letters from a template with the record's details filled in — thank-you letters, Gift Support acknowledgements, funder cover letters. Templates live on the 📄 Letters page.

• Create a template: give it a name, choose which record type it merges against (People, Grant applications…), and write the letter body. Drop in {token} merge fields — the editor lists every token available for the chosen type, plus {today} and {title}. A typo like {frist_name} is left visible in the letter so you spot it.
• One letter: open any record and click 📄 Letter — a .docx downloads with that record's details merged in, ready to print or post.
• A whole batch: on a list, filter down to the records you want (e.g. donors who gave last quarter), then click 📄 Letters on the toolbar. You get a .zip containing one .docx per record.

🕓 Record history

Every record keeps a permanent audit trail, shown in its Timeline tab: who created it, every field change with before → after values ("Amount: £50 → £75, by Sam"), and how it entered the system — an admin edit, CSV import, donation form, supporter portal, Xero import, workflow or the scheduler. History is append-only: it can't be edited or deleted, even by admins.

🧹 Duplicates & merging

The 🧹 Duplicates button on the People and Organisations lists finds likely duplicates — people who share an email address or a full name, organisations that share a name. For each pair, Merge… lets you:

1. Choose which record to keep (the other is merged in, then deleted).
2. Resolve any fields where the two records genuinely conflict.

Everything else is automatic: gaps on the kept record are filled from the other, emails and phones are combined without duplicates, and every linked record — payments, tasks, memberships, tickets, grants — is re-pointed to the kept record. The merge is recorded in its history. Nothing that referenced either record is lost.

🔐 Users, roles & security

• Roles are enforced on the server for every request — hiding a button is never the only protection.
• Passwords are stored with modern scrypt hashing; sessions are HttpOnly cookies; sign-in attempts are rate-limited per account.
• There must always be at least one active administrator — the system prevents removing the last one.
• Deactivating a user signs them out immediately and blocks sign-in, without deleting anything they did (their name stays in record history).

🔑 API access

Every signed-in user can create API keys from 🔑 API Access in the sidebar. A key acts with its owner's role — a read-only user's key is read-only — and keys can never manage users, other keys or passwords, so a leaked key can't mint itself more access. The plaintext key is shown once at creation.

The versioned read-only API lives at /api/v1: schema, filtered/paginated record queries, record detail with relationships, CSV export, and a one-call full-database export as JSON. Documentation is generated live from your own schema — custom types and fields included — at /api/v1/docs.

🚀 Deploying & backups

The app is one Node.js process with a single SQLite database file, so it runs anywhere with Node 22+ (or Docker) and a persistent disk — Render, Fly.io and Railway all work well and cost a few pounds a month. The essentials:

• Set the DATA_DIR environment variable to the persistent disk path — without it the database is wiped on every deploy.
• Visit the site immediately after first deploy to claim the admin account.
• Backups: the whole database is one file (crm.db) — download a copy on a schedule, or use continuous replication.
• Xero needs XERO_CLIENT_ID and XERO_CLIENT_SECRET set the same way.

The step-by-step platform walkthroughs (Render, Fly.io, Railway, custom domains, the Xero developer-app setup and a go-live checklist) live in the repository's DEPLOY.md file.