Read Me First

A plain-English introduction to the Practice Management System. If you have just been handed this project and you are not a software developer, start here. Nothing below assumes any technical background.

Ten minutes with this page should tell you what the software is, who it is for, what it can and cannot do today, and what to do first.

---

1. Who this is for

This software is built for the people who run a small or mid-sized healthcare practice — the kind of clinic with anywhere from one to a few dozen providers. Specifically:

• Practice owners and practice managers — the person accountable for whether the clinic gets paid, stays staffed and stays out of trouble with regulators.
• Office managers and front-desk coordinators — the people who own the appointment book, the phone and the patient roster.
• Billing staff and revenue cycle managers — the people who turn visits into claims and chase the money.
• Clinicians — doctors, nurse practitioners, therapists, physiotherapists, chiropractors and other allied-health providers who need to write up their visits.
• Whoever looks after IT and privacy compliance for the practice, whether that is a staff member or an outside contractor.

It suits general practice, behavioural health and allied-health clinics. It was designed first around United States billing rules, with support added for practices in Canada and Ireland.

One important note about audience: this is not a finished commercial product you buy and switch on. It is a working core system, entirely generated by AI, deliberately shipped with plain, unbranded screens. Think of it as the engine rather than the finished car. It is meant to be adapted — restyled, extended, and fitted to how your practice actually works — either by you with AI tools, or by someone you engage to do it. See "Where to get help" at the end.

---

2. What it does

The software keeps track of the whole life of a patient visit, from the moment it is booked to the moment the money arrives.

You book appointments on a shared calendar. You keep patient records, including their insurance details. When the patient is seen, the clinician writes up the visit and records what was diagnosed and what was done. The system turns that into an insurance claim, sends it off, and tracks what comes back — paid, partly paid or refused. You can take card and cash payments from patients at the desk. Managers can run reports on how much was billed, how much was collected, and where money is getting stuck.

Alongside that, it keeps a permanent record of who looked at which patient file, because health privacy law requires that, and it has a separate small website where patients can log in to see their own appointments, balance and messages.

Some AI assistance is built in: predicting which patients are likely to miss appointments, checking claims for errors before they go out, and drafting a clinical note from a transcript of the visit. These are real features in the codebase, though several are switched off by default and are not active in the evaluation image (see the FAQ).

---

3. The domain: what a practice management system is for

If you have never worked in a clinic's back office, here is the setting.

A medical practice earns money by seeing patients, but in most countries it does not get paid by the patient. It gets paid by an insurer or a public health scheme. That creates a long, fragile chain between doing the work and being paid for it, and almost every step can break.

The chain looks roughly like this:

1. Booking. A patient asks for an appointment. Someone has to find a slot with the right provider at the right location. If the patient does not turn up, that slot earns nothing — and it is usually too late to fill. Missed appointments ("no-shows") are one of the biggest quiet losses in a practice.
2. Checking the cover. Before the visit, the practice should confirm the patient's insurance is actually active and what it covers. Skipping this is how you end up doing work nobody will pay for.
3. The visit. The clinician sees the patient and writes it up. That write-up is both a medical record and the evidence for the bill. Too little detail and the claim gets refused; the wrong code and the practice is either underpaid or, worse, over-billing.
4. Coding. The visit gets translated into standard codes: what was wrong with the patient (diagnosis codes) and what was done about it (procedure codes). This is a specialist skill and the source of much of the industry's argument.
5. The claim. Those codes become a formal claim sent to the insurer, usually via a middleman called a clearinghouse. The claim has to be structured exactly right.
6. The response. Weeks later the insurer replies: paid in full, paid in part, or refused with a reason code. Refusals ("denials") must be understood, fixed and resubmitted, or the money is simply lost.
7. The patient's share. Whatever the insurer does not cover — co-pays, deductibles, balances — has to be collected from the patient.
8. Proving you behaved. Throughout, patient information is legally protected. In the US this is HIPAA; in Europe and Ireland, GDPR. Practices must control who can see what, keep records of who looked at what, train their staff, hold signed agreements with vendors who touch patient data, keep working backups, and be able to report a privacy breach within a deadline.

A practice management system is the software that holds this chain together. Note what it is not: it is not primarily a clinical record system for complex hospital medicine, and it is not an accounting package. It is the operational and financial spine of an outpatient clinic.

Practices today typically pay for this either as a percentage of everything they collect (commonly in the region of 4–7%) or as a monthly fee per provider. This project exists as an open, self-hostable alternative to that.

---

4. Where it fits: the world around it

This software does not work alone. Expect it to sit in the middle of several outside relationships.

The people who use it

• Your own staff, signing in with their own accounts and seeing only what their job requires.
• Your patients, through a separate patient-facing site where they can view appointments, balances, messages and intake forms.

The outside services it is built to talk to

• Clearinghouses and insurers. The system is built to send claims and eligibility checks to a clearinghouse — the industry's postal service between clinics and insurers. The shipped connector targets Availity, and it is written so a different clearinghouse can be substituted. Nothing works here until you have your own account and credentials with one.
• Text-message and email providers. Appointment reminders, notifications and emailed reports go out through Twilio (texts) and SendGrid (email). Again, your own accounts.
• A card payment provider. Card payments run through Stripe, deliberately, so that card numbers never live inside this system.
• An identity provider for staff sign-in. The system can hand staff login over to an external single-sign-on service, as an alternative to keeping passwords itself.
• Other health software. There is a standards-based interface (FHIR) so other approved systems and patient apps can request records in a common format, rather than through private one-off integrations.

Two things to budget for that are not software

• Procedure code content is licensed. In the United States, the CPT procedure code set is owned by the American Medical Association and requires a paid licence. This project ships the place to put those codes but not the codes themselves, and the feature is switched off by default until you are licensed. Diagnosis codes (ICD-10) are free to load.
• Compliance is a practice obligation, not a software feature. The system helps you evidence good behaviour. It cannot make you compliant on its own.

---

5. First run: the very first thing to do

Look at it before you commit to anything.

There is a self-contained evaluation package — a preview image — that runs the entire system on one computer with a single command and no setup. It arrives already populated with a fictional practice called "Lakewood Family Medicine": twenty invented patients, sixty appointments, forty claims. Nothing real, nothing sent anywhere.

The instructions are in preview/README.md. In short: install Docker, run the one command in that file, wait up to two minutes for it to prepare itself, then open the address it gives you in a browser.

Sign in as the demo administrator — the email addresses and the shared demo password are listed in preview/README.md. Use the administrator account first, because it is the only account that currently sees the full navigation menu (see the FAQ).

Then spend fifteen minutes clicking through it in this order, which is roughly the shape of a real day:

1. The dashboard — patient count, claims outstanding, claims paid.
2. The patient list — search by name, record number or date of birth.
3. The scheduling calendar — a week at a glance, one column per provider.
4. Billing — the list of claims and their states.
5. Reports — pick a date range and look at the receivables and provider panels.

A guided tour matching these screens, written for exactly this purpose, is in docs/walkthrough-screenshots/.

Two warnings about the preview. It is for evaluation only — never put real patient information into it. And unless you deliberately attach a storage folder, everything you type into it is thrown away when you stop it. That is a feature: click around freely.

---

6. Setting up a real environment

When you have decided to proceed, this is the order of work. Most of it needs a technical person alongside you; your job is the decisions, not the commands.

Step 1 — Decide where it lives. The system can run on your own server in the practice, or on a cloud server you rent. Either way it needs to be a properly secured, encrypted, backed-up environment. The evaluation image is explicitly not suitable for real patient data. The technical requirements are in installation/installation-guide.md and technical/technical-documentation.md.

Step 2 — Create the practice and the first administrator. There is a one-time initialisation step that creates your single practice record and your first owner login, and nothing else. You will need to decide, before running it: the practice's legal name, its time zone, its country, and the email address and password of the first administrator. This step deliberately wipes the database first, so it is run once, at the very beginning, never again. The full procedure and its safety catches are in production-first-use-setup.md.

Note that each running installation serves exactly one practice. If you operate two separate legal practices, that is two installations.

Step 3 — Load the code sets. Diagnosis codes must be loaded from the official public release. Procedure codes require your AMA licence first, and stay switched off until then. Without these, coding and claims cannot work properly.

Step 4 — Set up your people. Create an account for every staff member and give each one the narrowest role that lets them do their job. Turn on two-step sign-in for anyone with administrative access. Do not share logins — the audit trail is only worth having if each entry points at one real person.

Step 5 — Describe your practice. Enter your locations, your providers and their working hours, the types of appointment you offer and how long each takes, and the insurers you deal with. This is the tedious part and it determines whether the calendar is usable.

Step 6 — Connect the outside services. For each of the following you obtain an account with the provider, then have your technical person put the credentials into the system's configuration: the clearinghouse (claims and eligibility), the text-message provider, the email provider, and the card payment provider. Each can be left unconfigured; the related feature simply stays inactive. Test each one with a single deliberate transaction before you rely on it. integration/integration-guide.md covers this in detail.

Step 7 — Set your jurisdiction and language. Choose the country your practice operates in, which drives the regulatory framework, currency, default language and sales-tax handling on invoices. Staff can set their own interface language; patients have a preferred language on their record. English and Spanish interface translations ship today.

Step 8 — Bring your data across. Existing patient records and history come in through the system's programming interface rather than a point-and-click importer. Plan this as a small project with your technical person: extract from the old system, load a sample of twenty patients, check them by hand, then do the rest. Never move real data into an environment you have not yet secured, and never treat the migration as done until someone who knows the patients has spot-checked it.

Step 9 — Run a parallel week. Before switching off whatever you use today, run both for a week. Book the same appointments in both, submit a handful of real claims through the new system, and confirm the money arrives. This is where you find the gaps that matter to your practice.

---

7. Day to day

Here is what routine use actually looks like, by role.

Front desk

Morning. Open the dashboard for the shape of the day, then the calendar. The week view shows one column per provider with each booking in place and a colour for its state — booked, arrived, completed, cancelled.

Booking a patient. Search the patient list by name, record number or date of birth. If they are new, create the record; the system assigns a medical record number automatically. Add their insurance details, and check the cover is active before the visit. Then find a free slot with the right provider and book it. The system refuses to double-book a slot, so two staff booking at the same moment cannot collide.

Arrivals. Mark each patient as arrived when they check in. That is what tells the clinician the patient is ready, and it is what starts the visit record.

Waitlist. Patients who want an earlier slot go on the waitlist with their preferences, so that when a cancellation frees something up you already know who to call.

Money at the desk. Co-pays and outstanding balances are collected on the payment screen: find the patient, enter the amount, choose the method, note what it was for. Card payments go through the payment provider; cash, cheques and transfers are recorded straight against the patient's account.

Clinicians

Open the day's list, open the patient's visit, and write the note. Notes follow the familiar four-part structure — what the patient reported, what you observed, your assessment, and the plan. Record the diagnoses as proper codes, with one marked as the primary reason for the visit, because that is what the claim will be built from.

A note is a draft until you sign it. Once signed it is locked; corrections are made as a formal amendment that preserves the original, and where supervision applies a supervisor co-signs. This is deliberate: the chart has to be defensible later.

Where the AI drafting feature is enabled and configured, you can paste or dictate the conversation from the visit, confirm the patient consented to being recorded, and have a first draft written for you. The draft is clearly marked as AI-generated and unreviewed, and a clinician still has to read, edit and sign it. Accountability does not transfer.

Billing

Work from the claims list: claim number, patient, date, amount and status in one view. Completed, coded visits become claims. Submit the drafts. Watch for what comes back.

When an insurer's payment advice arrives, the system matches it to the claim, records what was paid on each line and stores the reason codes for anything reduced or refused. Refused claims go into a denials view grouped by insurer and reason, so you can see the patterns rather than fighting one claim at a time — for example, one insurer refusing the same code repeatedly is a fixable process problem, not bad luck.

Where the claim-checking feature is enabled, claims are examined before submission: clear rule violations block the submission, while softer risks are flagged as warnings you can choose to ignore.

Managers

Use the reports screen. Pick a date range and the system works out the picture: total charges, total collections, collection rate, denial rate, average days waiting to be paid, and the proportion of claims accepted first time. Underneath, unpaid money is grouped by how old it is, refusals are broken down by insurer, and providers are compared with each other.

Anything on that screen can be put on a schedule — daily, weekly or monthly — and emailed to whoever needs it, with a delivery history so you can see whether it actually arrived.

---

8. Ongoing care

Some things are not daily but will hurt you if nobody owns them. Assign each of these to a named person.

Weekly

• Work the denials list. Refused claims have deadlines; a month of inattention is money gone.
• Look at unpaid balances by age. Anything drifting past ninety days needs a decision.
• Check the appointment book for next week against provider availability.

Monthly

• Review the revenue-cycle report against the previous month, and act on the outliers rather than just filing it.
• Review who has an account and what it can do. Remove people who have left, the same day they leave.
• Confirm your backups are not only running but restorable. The system tracks backup verifications and restore drills, and will show a failed backup as failed rather than quietly forgetting it — but somebody has to look.

Quarterly

• Run an access recertification: every person's access is reviewed and either confirmed or withdrawn. The system runs this as a campaign with decisions recorded per person.
• Tidy the patient list: merge duplicate records, retire inactive ones.
• Check staff privacy training is current and that signed agreements with vendors who handle patient data have not expired. Both are tracked in the compliance area, with anything expired or missing highlighted.

Annually, or when something changes

• Full review of roles and permissions.
• Review the insurers, fees and appointment types you have configured — they drift out of date quietly.
• Confirm your procedure-code licence is current before the codes go stale.

When something goes wrong

Privacy incidents get logged in the compliance area as soon as they are suspected, and are tracked through investigation against the legal notification deadline. Log first, investigate second. The deadline runs from discovery, not from when you finish looking into it.

Requests from patients about their data

Where privacy law gives patients the right to a copy of their data or to have it erased, those requests are recorded and tracked through to completion, so you can show they were handled.

---

Glossary

• Claim — a formal request to an insurer to pay for a visit.
• Clearinghouse — a middleman service that carries claims and eligibility questions between clinics and insurers, and translates between their formats.
• Denial — an insurer refusing to pay a claim, always with a coded reason.
• Eligibility check — asking an insurer, before the visit, whether the patient's cover is active and what it includes.
• Encounter — the record of one visit: who saw whom, when, what was found and what was done.
• ERA / remittance advice — the insurer's electronic statement of what it paid, what it reduced, and why.
• FHIR — a common standard for passing health records between different systems.
• GDPR — European and Irish data protection law, which gives individuals rights over their own data.
• HIPAA — the United States law governing the privacy and security of patient health information.
• ICD-10 — the international code set for diagnoses. Free to use.
• CPT — the United States code set for procedures and services. Requires a paid licence from the American Medical Association.
• MRN (medical record number) — the practice's own unique identifier for a patient.
• No-show — a booked patient who neither attends nor cancels.
• NPI — a national identifying number for a US provider or practice, required on claims.
• PHI (protected health information) — patient information that the law protects.
• Payer — an insurer or scheme that pays for care.
• A/R (accounts receivable) — money billed but not yet received. "Days in A/R" is how long it typically takes to arrive.
• SOAP note — the standard four-part clinical write-up: Subjective, Objective, Assessment, Plan.
• Single-tenant — one installation serves exactly one practice.

---

The rest of the documents here

Everything below lives under user-docs/.

Document	What it is for	Who should read it
READ-ME-FIRST.md	This orientation page	Everyone, first
user-guide/user-guide-layman.md	Plain-English, step-by-step instructions for everyday tasks — logging in, booking, checking in, writing a note, submitting a claim, running a report, adding a user	Front desk, clinicians, billing staff
user-guide/user-guide-detailed.md	The full reference: every module in depth, including user management, notifications, integrations and the audit trail	Practice managers, power users, trainers
installation/installation-guide.md	Getting a working installation stood up and configured, end to end, with a post-setup checklist and troubleshooting	Whoever installs it
production-first-use-setup.md	The one-time initialisation that creates your practice and first administrator, and its safety catches	Whoever installs it, with the practice owner present
integration/integration-guide.md	Connecting outside systems: authentication, calendars, the clearinghouse, other health record systems, event notifications, error codes and rate limits	Technical staff or your integration contractor
technical/technical-documentation.md	Architecture, security controls, HIPAA posture, data model, retention, backups and incident response	Technical due diligence; your IT or security reviewer
whitepapers/whitepaper-practice-owner-roi.md	The business argument: where practices lose billable revenue and what recovering it is worth	Practice owners, finance
whitepapers/whitepaper-it-security-compliance.md	Technical due diligence on HIPAA safeguards and interoperability	Healthcare IT and compliance leaders
marketing/marketing-copy.md	Brand voice, terminology and ready-made promotional copy	Anyone presenting or reselling this
website/index.html	A ready-made product web page	Marketing
store-thumbnail.png	Product thumbnail image	Marketing

Also worth knowing about, outside user-docs/: preview/README.md (how to run the evaluation image, and the demo logins) and docs/walkthrough-screenshots/ (a narrated tour of the real screens, plus an honest list of the current rough edges).

---

Who can do what: roles

Every staff member gets an account with one or more roles, and the system checks the role on every action — both in what the menu shows and in what the server will allow.

The roles that exist in the running system are:

Role	Intended for	Typically can
admin	Practice owner, practice manager	Everything: practice settings, user accounts, compliance, jurisdiction and language settings, plus all clinical and billing screens
practitioner / clinical	Doctors, nurses, therapists	Their schedule, patient records, visits and clinical notes
front_desk	Receptionists, coordinators	The calendar, booking, patient records, check-in, taking payments
billing	Billers, revenue cycle staff	Claims, remittances, denials, patient payments, reports
compliance_officer	Whoever owns privacy	The compliance area: incidents, training records, vendor agreements
security_officer	Whoever owns security	Access recertification and security-sensitive administration

Two honest observations about the current build:

• The administrator role is the one that works cleanly today. The sidebar menu and the server disagree about the exact spelling of some role names, with the result that a practitioner or front-desk user can sign in successfully but see an empty navigation menu. Evaluate with the administrator account; treat this as a known defect to fix before anyone else uses the system in earnest.
• The compliance and jurisdiction screens are not in the menu at all. They exist and work, but you reach them by typing their address directly. Also a known gap.

Separately from staff, patients sign in to their own site with their email address and date of birth, and can only ever see their own records. Note that this is weaker than the passwordless email-link sign-in the specification describes; it is what is actually built today.

Beneath all of this, every view of and change to patient information is written to a permanent audit record — who, what, when, and from where. Nobody can switch that off, which is the point.

---

The demo data, and starting fresh

The evaluation image comes preloaded with a fictional practice so that every screen has something in it:

• One practice, "Lakewood Family Medicine", across two locations
• Eight staff accounts: an administrator, five providers, one front-desk and one billing user
• Twenty invented patients with plausible details and insurance
• Three fictional insurers
• Sixty appointments — some completed, some cancelled, some missed, some upcoming, some arrived today
• Forty claims spread across various states
• No-show predictions for the upcoming appointments

None of it is real, and none of it goes anywhere: card payments appear to succeed without any charge, and reminders are recorded internally rather than sent.

To start fresh in the evaluation image, simply stop the container and start a new one. Unless you deliberately attached a storage folder, everything resets to the original demo state. If you did attach one, delete its contents — or point at an empty folder — and the system rebuilds the demo practice on next start.

To start fresh for real use, do not clear the demo data; use a separate, properly secured installation and run the one-time initialisation described in production-first-use-setup.md. That creates your practice and your first administrator and nothing else — no invented patients. Keep demonstration and real environments completely apart, always.

---

FAQ and common gotchas

Is this ready to run my clinic tomorrow? No. It is a working core with real functionality and some real rough edges, shipped deliberately plain so that it can be adapted. Treat it as a strong starting point that needs finishing work, not a product you switch on.

Can I put real patient data in the evaluation image? No. It is explicitly not built for that. Real patient data belongs only in a properly secured installation.

Why is the patient chart page broken? Opening an individual patient's chart currently fails in the evaluation build, because of a mismatch between how contact details are stored and how the page reads them, and because two of its panels ask for addresses that do not exist. The patient list itself works fine. This is a known defect.

Why can't I book an appointment by clicking an empty slot? The booking window does not open in the current build — the calendar and the booking form disagree about how to talk to each other. Another known defect, and a high one to fix, since booking is the most-used function in any practice system.

Why are the revenue figures at the top of the reports screen empty? The financial summary is calculated from when each claim was submitted, and the demo data never records a submission date. The panels below it — unpaid money by age, and provider comparison — do populate. This is a demo-data limitation rather than a broken report.

Why does the waitlist page say it failed to load? The page asks the server for the waitlist at the wrong address. Known defect.

I enabled AI note drafting and nothing happened. The drafting feature is switched off by default, and the evaluation image does not include the service that performs it. You will see the transcript and consent screen, but generating a draft falls back to writing it yourself. Anomaly detection is off by default too. These are configuration and packaging choices, not missing code.

The compliance backups list stops working after I record a backup. There is a data-formatting fault in how backup sizes are returned; one affected record makes subsequent requests for the backup list fail. Similarly, recorded training completions are accepted but do not yet show as completed. Both are known defects in the compliance area.

Why can't I use procedure codes? Because they are licensed. Obtain an AMA licence, load the code content, then enable the feature. This is a legal constraint that applies to any US practice management system, not a limitation of this one.

No reminders are being sent. Reminders need a text-message and email provider configured with your own credentials. Until then they are recorded internally and go nowhere.

Claims are stuck as queued. When the clearinghouse cannot be reached, claims queue and retry automatically with growing gaps between attempts, then are marked as failed if they never get through. Check that the clearinghouse credentials are configured and that the background worker is running.

Can I run several practices on one installation? No. One installation, one practice, by design. Run separate installations.

Where did the single-sign-on option go? It is hidden in the evaluation image, because it needs a real external identity service that does not exist offline. Use the demo passwords instead.

Why does it look so plain? On purpose. The screens carry no styling or branding so that you can apply your own. What you are evaluating is the behaviour, not the appearance.

---

Where to get help

The community behind this project lives at wbsp.ai.

Go there to:

• Ask questions and report problems, including the defects listed above.
• Look at what other people have built. Community members have produced many variations of this and other applications, and one may already be closer to what you need than this baseline.
• Find people who do this work — if you want the system branded, extended and fitted to your practice, and would rather not do it yourself.

The project is open source and contributions are welcome, from developers and from clinic people with hard-won domain knowledge. Honest descriptions of how your practice actually works are, genuinely, as valuable as code.