Help & User Guide

Testing vs live use

You may test with dummy records on any server, as demonstrated at soul-trade.com/cspractice. Once you begin entering real patient data, ensure your server meets the security requirements below — HTTPS enabled, field encryption turned on (Setup → Security), and config.php backed up securely. With these in place, an internet-accessible shared hosting server is a perfectly valid live environment.

Minimum technical requirements

Internet vs intranet — why it matters

An intranet installation runs on a server that is only accessible from within your practice network (or via VPN). Patient data never leaves your building. This is the recommended approach for any practice holding real patient records. This can be as simple as using an older computer (e.g. a Raspberry Pi 4 — around £55 new, silent, pocket-sized, uses 3W of power and runs 24/7 — an old Mac or Windows laptop, or NAS device running Linux) and simply copy/pasting the commands shown in the 🫐 Raspberry Pi installation guide, Apple Mac installation guide or the Windows installation guide — all written for non-technical practitioners.

An internet installation is accessible from anywhere — convenient for multi-site practices, but requires stronger security measures: strong passwords, regular security updates, firewall rules, and ideally IP whitelisting.

Intranet setup options

• Local server on practice premises — a small dedicated machine (e.g. a Raspberry Pi 4, old Mac or Windows laptop or desktop, or NAS device running Linux) running Apache, PHP and MySQL. Accessible only on your practice WiFi. Low cost, high control.
• Practice network with VPN — server on your local network, accessible remotely via VPN tunnel. Practitioners can access from home or between sites securely.
• Private cloud server (UK-based) — a virtual private server (VPS) with a UK hosting provider, firewall-restricted to your IP addresses. Examples: Mythic Beasts, Bytemark, IONOS UK. Avoid US-based providers unless you have specific legal advice on international data transfers.

UK GDPR obligations for healthcare practitioners

Patient health data is special category data under UK GDPR (Article 9). As a data controller you are required to:

• Register with the ICO — most healthcare practitioners must register as data controllers. Annual fee applies (currently £40–£60 for small organisations). Check ico.org.uk.
• Privacy notice — provide patients with a clear privacy notice explaining what data you hold, why, how long you keep it, and their rights. This can be a leaflet or a statement on your website.
• Lawful basis — for healthcare, the lawful basis is typically vital interests or legitimate interests combined with explicit consent for special category health data.
• Retention policy — NHS guidelines recommend retaining adult patient records for 8 years after last treatment (longer for children). You must define and document your retention period.
• Data subject rights — patients can request a copy of their data (Subject Access Request), ask for corrections, or request deletion. You must be able to respond within 30 days.
• Data breach procedure — you must have a process for identifying and reporting data breaches to the ICO within 72 hours if required.

Professional body requirements

The GOsC, GCC, CNHC and other UK regulatory bodies all require members to comply with data protection law as a condition of registration. Your indemnity insurance provider may also have specific requirements around clinical record keeping and data storage.

Recommended reading

• ICO Guide to UK GDPR — ico.org.uk/for-organisations/uk-gdpr-guidance-and-resources
• NHS Records Management Code of Practice — england.nhs.uk
• GOsC Standards of Practice — osteopathy.org.uk
• CNHC Code of Conduct — cnhc.org.uk

Each patient record has an Attachments tab for storing scanned documents, X-ray reports, GP letters, referral notes, insurance forms and any other files relating to that patient.

Supported file types

PDF, JPG, PNG, GIF and WebP. Maximum file size 10MB per file. For larger files (e.g. high-resolution X-rays) reduce the scan resolution before uploading.

Uploading a file

Open the patient record, click the Attachments tab, and use the upload form. You can:

• Add a title to describe the document (e.g. "GP referral letter Jan 2025")
• Optionally link to a session — useful for X-rays or reports from a specific visit
• Optionally link to a letter — useful for the incoming letter that prompted an outgoing referral
• Add notes about the document

Viewing files

Uploaded files appear as a card grid. PDFs show a document icon, images show a thumbnail preview. Click Open to view the file in a new browser tab. PDFs open directly in the browser; images display inline.

Emails

Emails don't need a separate attachment mechanism — copy and paste the relevant content into the patient's yellow notes field or save it as a letter record. For emails with important attached documents, save the attachment as a PDF and upload it here.

Server setup required

Attachments are stored in a folder called cs_attachments located one level above the web root — outside publicly accessible directories. This must be created manually and the path configured in config.php:

define('ATTACH_PATH', '/full/path/to/cs_attachments');

See the Mac or Windows installation guide for the correct path for your setup.

Access control

All logged-in users can view attachments. Only Medium Level and above can upload or delete files.

The Audit page is accessed from the main navigation. It provides a cross-tab query builder that searches across all clinical fields simultaneously — demographics, conditions, examination findings, medicines, treatments, practice details and dates. This is the feature that makes structured data entry pay off.

Building a search

The left panel is the query builder. Start with one empty row — choose a field from the dropdown, the input type changes automatically to match:

• Text fields — free text, searches for any match containing your value
• Select fields — dropdown of available values (Sex, Smoker, Prognosis etc.)
• Boolean fields — ticked fields like State Acute, Maintenance, New Condition — just shows "is set", no value needed
• Age range — min and max age in years
• Date range — from and to date pickers
• SLR degrees — finds patients with SLR at or below the value entered
• Improvement min % — finds patients at or above the improvement level

Click + Add criterion to add more rows. All criteria are combined with AND — every condition must be met. Click Search to run.

Searchable fields

Results

Results show Name, Age, Sex, Primary condition, Location, Last seen, Treatment, Improvement and Practitioner. Click any name to open that patient record. Results are limited to 500 — if your search returns the limit, refine your criteria.

Tagging a cohort

Once you have a results list, click 🏷 Tag cohort to reveal the colour picker. Select a colour and click Apply Tag — all matching patients are tagged with that colour simultaneously. You can then filter the Patients list by that colour to work with the cohort.

Colours carry no fixed meaning — you decide what each colour represents for a given audit project. Clear the colour when your analysis is complete.

Open text search

At the top of the Search Criteria panel is a free-text search box. Type any word or phrase and it searches across all major text fields simultaneously — name, address, notes, precautions, condition, treatment history, diagnosis, session notes and treatment plan titles and goals. Useful for "I know it's in there somewhere" searches.

Saving searches

After running a search, a Save this search panel appears below the query builder. Give it a name, an optional description, and optionally tick Share with all users to make it available to all practitioners. Saved searches appear in the Saved Searches panel and can be run again with one click.

The Statistics page is accessed from the main navigation. It has three tabs — Practice Dashboard, Clinical, and Cohort — filtered by year and practitioner.

Practice Dashboard

Summary cards at the top show sessions this month, sessions this year, sessions all time, income this month, income this year, new patients and active patients. Below these are four charts:

• Sessions per month — bar chart of the last 12 months
• Income per month — bar chart of the last 12 months
• Top conditions — horizontal bar chart of the most common presenting conditions for the selected year
• Referral sources — doughnut chart showing how patients found the practice

Clinical tab

Deeper clinical analysis for the selected year:

• Sex breakdown — doughnut chart of patient sex distribution
• Age breakdown — bar chart by age group
• Improvement distribution — doughnut showing what percentage of sessions resulted in each level of reported improvement
• Treatment frequency — horizontal bar of most used treatments
• Average improvement by condition — table showing mean improvement % per condition (minimum 3 sessions)
• Average sessions per patient by condition — table showing how many sessions on average it takes per condition

Cohort / Audit tab

Select a colour-tagged patient cohort to analyse. Colour-tagged cohorts are created on the Audit page — search for patients, then tag the results with a colour. The cohort tab then shows:

• Summary cards — patient count, total sessions, average sessions per patient, average improvement
• Six charts — conditions, sex, age, therapy type, improvement distribution, treatments used

This is the research view — tag a cohort on the Audit page, then come here to see the statistical breakdown of that specific group.

Filters

Year and practitioner dropdowns at the top apply across all three tabs. Select a specific practitioner to see their individual statistics, or leave on All practitioners for the whole practice.

The Case History page is the detailed clinical intake record — accessed via the 📋 Case History button on any patient record. It has four tabs, each saving independently so you can fill them in stages without losing work.

The mosaic input pattern

Throughout Page 2, input works on the mosaic principle — choose a value from the dropdown, click the ↓ arrow, and it appends to the yellow text field below on a new line. You can then type freely in the text field to add your own words. Come back and add more at any time. Type the first letter of a value to jump to that part of the list.

The yellow text field is what gets saved — it becomes a cumulative, readable clinical record that also feeds the audit search engine.

Tab 1 — Medical History & Cranial

• Past Medical History & Cranial — mosaic field covering Surgery, RTA, Fracture, Ca, Hysterectomy, Children, Serious illness, Operations, and cranial findings (Stuck, Free, Torsion, Equal)
• Secondary Conditions — mosaic field for concurrent presenting complaints, same value list as primary condition
• Condition Duration — how long the condition has been present and in what units
• Accident / RTA — type of trauma and how long ago
• Pain Map — interactive front and back body diagram. Select a paint colour (yellow = mild through to purple = very severe), then click any body zone to colour it. Click again to change colour. Accumulated over time — update when the pain picture changes.

Tab 2 — Examination

Seven satellite dropdowns (Structural, CV/Resp, Abdominal, Neurological, Smell, Eyes/Skin, Bowels/Tongue) each feed into one central yellow findings text box. Choose a finding from any satellite, click ↓, and it appends to the findings record.

• State — Acute, Chronic, New condition, Maintenance, Nerve radiation
• SLR — straight leg raise in degrees, left and right
• Better / Worse — aggravating and relieving factors
• Smoker — status and how long ago if ex-smoker
• Improvement — percentage improvement reported by patient
• Pain Colour Indicator — overall pain intensity summary

Tab 3 — Movement & Emotion

A mosaic snapshot of the patient's lifestyle and emotional context — one of the most clinically useful fields in the system. "Dog, gardening, recently divorced, fragile, needs holiday" tells you more about a patient in five seconds than a structured questionnaire.

The value list covers exercise, hobbies, mobility, social situation, emotional state, beliefs and lifestyle. All values are editable in Setup → Value Lists → Movement & Emotion.

The Five Elements dropdown (Wood / Fire / Earth / Metal / Water) sets a colour indicator and shows the associated organ systems, season, emotion and characteristics. Links to the Five Elements & Pulse History page (coming soon).

Tab 4 — GPs & Admin

• GP — linked from the Contacts database. Used to auto-populate GP referral letters. Note: the GP dropdown will be empty on a fresh installation — add your GPs first via Contacts → New Contact (type: GP), then return here to link them to patients.
• Other Therapists — free text list of other healthcare providers
• Referral Source — how this patient found the practice
• Relationship — patient's relationship to the practice (Patient, Son, Daughter, Husband, Wife etc.)
• Insurance — insurance company

Editing value lists

All the dropdown lists in Page 2 are editable in Setup → Value Lists. The page shows an index at the top — click any list name to jump to it. Add new values with the + Add button. Remove values with the ✕ button. Changes take effect immediately. Other editable value lists are in Contacts (GPs and therapists), Medicines and in Setup where you can add practice locations (and practitioners who are the Users)

Page 3 is accessed via the 💊 Rx button on any patient record. It records the prescribing and treatment picture — diagnosis, prognosis, medicines prescribed and treatments given — all using the mosaic append pattern.

Layout

The page is divided into four quadrants:

• Top left — Medicine History — five dropdown lists feeding one yellow text box
• Bottom left — Treatment History — treatment list with date stamp button feeding a yellow text box
• Top right — Differential Diagnosis — mosaic dropdown feeding a yellow text box
• Bottom right — Prognosis — mosaic dropdown feeding a yellow text box

Medicine History

Five separate dropdown lists each feed the same central medicine history text box:

• Standard — conventional prescription and OTC medicines
• Supplement — vitamins, minerals and nutritional supplements
• Herbal — herbal medicines and tinctures
• Homeopathic A–N — homeopathic remedies A through N
• Homeopathic O–Z — homeopathic remedies O through Z

Select from any list, click ↓ to append to the medicine history. Type the first letter to jump to that part of the list. The text box is fully editable — add dosages, frequencies and notes freely.

Treatment History

The treatment list covers the full range of techniques used across therapy types:

GOT · AK · Meridian · Mobilize · Recommend · TreatmentIncluded · HVT · Cranial · Facial · SoftTissue · Hydrotherapy · StrainCounterStrain · MET · Naturopathic · Osteopathy · Acupuncture · Chiropractic · Physiotherapy · Chiropody · Counselling · Reiki · Herbalism · Aromatherapy · Reflexology

The 📅 Date button inserts today's date as a divider — useful for building a chronological treatment record across multiple visits.

Differential Diagnosis

Choose from the diagnosis value list (Musculoskeletal, Neurological, Visceral, Cranial, Naturopathic etc.) and append to the diagnosis text box. Add your own clinical detail freely in the text box.

Prognosis

Excellent / Good / Fair / Guarded / Poor / Refer — append and annotate as the clinical picture evolves.

Medicine lists

The standard medicine, supplement, herbal and homeopathic lists are large reference lists. They can be managed via Setup → Value Lists. A dedicated medicines management interface with search and pagination will be added in a future version for easier management of the full lists.

The Treatment Plan is accessed via the 📋 Plan button on any patient record. It records a structured plan of up to 5 clinic-based and 5 home-based goals, tracks achievement, and produces a printable summary to show the patient.

Milestone 1 — Clinic Based (Practitioner Goals)

Up to 5 practitioner-led goals — techniques, referrals or clinical objectives. Choose from the dropdown list or type your own. Goals show in red when still to do. Click the checkbox when a goal is achieved — it turns green with strikethrough. A positive image for both patient and practitioner.

Milestone 2 — Home Based (Patient Goals)

Up to 5 patient-led goals — exercise, lifestyle, self-care. Same layout and colour coding as Milestone 1. The same goal list is available for both milestones.

Review tab

Shows both milestones side by side with a progress bar (e.g. 3/5 achieved) and achievement dates. The Print / Show Patient button opens a clean printable page — red for still to do, green strikethrough for achieved. This can be printed and given to the patient or displayed on screen during the consultation.

Goal value list

The Treatment Plan Goals list is editable in Setup → Value Lists → Treatment Plan Goals. Add your own goals, remove ones you don't use. Both milestones share the same list.

The Podiatry page is accessed via the 👣 Podiatry button which sits to the left of the Edit Baseline button at the top right of the Examination Findings card on the patient's Examination tab.

Six finding groups

How to use

Select Left, Right or Both at the top. Choose a finding from any dropdown and click → to append to the yellow notes field as:

Left · Forefoot · Bunions

Type the first letter in any dropdown to jump to that part of the list. The notes field is fully editable — add your own observations freely.

Where findings appear

Podiatry notes appear as a read-only yellow card at the bottom of the Examination tab on the patient record, with an Edit link back to Page 6. They are stored separately from the baseline examination findings.

Value lists

All six podiatry finding lists are editable in Setup → Value Lists — look for the six Podiatry entries in the index. Add new conditions, remove ones you don't need.

Page 4 is accessed via the 🩻 Imaging button on any patient record. It provides a dedicated store for imaging records — X-rays, MRI, CT scans, ultrasound and other investigations — separate from the general attachments system.

Adding an imaging record

Each imaging record captures:

• Date, imaging type and region — e.g. X-ray · Lumbar
• Requested by — GP, self-referred, specialist, hospital etc.
• Findings checkboxes — grouped into Disc, Vertebrae, Alignment, Soft tissue and Other. Quick-tick common findings (disc degeneration, osteophytes, scoliosis etc.) without typing
• Practitioner's interpretation — your own clinical notes on the findings
• Radiologist's / specialist's report — paste the formal report text
• Image upload — attach the actual scan image (JPG, PNG, WebP) or a PDF report, up to 20MB

Viewing imaging records

Saved records appear as cards showing a thumbnail of the image. Click a thumbnail to open it full-screen in a lightbox viewer. PDF reports open in a new tab. Finding tags (disc degeneration, osteophytes etc.) are shown as small pills on each card.

Image files

Images are stored in the attachments/[patient_id]/imaging/ folder on the server — separate from general attachments. Make sure this folder is writable by the web server. Supported formats: JPG, PNG, WebP, GIF and PDF.

Page 5 is accessed via the ☯ Elements button on any patient record. It requires a Date of Birth to be recorded for the astrological calculations. It has five tabs.

Tab 1 — Five Elements

An interactive pentagon showing the five elements in their generating cycle. Click any element in the pentagon to make it central — all text panels, the organ line, the pulse dropdown and the colour scheme update instantly to reflect that element.

• Left panel — elemental personality text (the Wood person has high morals...)
• Centre — the pentagon with generating cycle (outer) and controlling cycle (inner dashed lines). The organ/emotion/taste/smell line shows below it.
• Right panel — direction and environmental text (Wood = East, growth, new beginnings...)
• Controls — element dropdown, Yin/Yang/Strong/Weak radio buttons, pulse quality dropdown (auto-set from element), two practitioner note boxes

Tab 2 — Feng Shui

The same five elements component with the panels repositioned — direction text on the left, pentagon in the centre, personality text on the right. The same click-to-recentre interaction applies.

Tab 3 — Pulse History

A structured pulse recording tool. Set a date, select quality and value for each of the 6 positions (3 left hand, 3 right hand), then click the ↓ arrow to append a timestamped entry to the pulse history record:

02/10/2024 * +5 +4 +3 +5 +4 +3 * floating sinking rapid hesitant slow hesitant

The history accumulates over time, providing a longitudinal pulse record for comparison across visits. Left hand positions shown in red/green/blue, right hand in green/yellow/red.

Tab 4 — Astrology (3 sub-tabs)

Western — sun sign calculated automatically from DOB. Shows the sign symbol, dates, element, modality and ruling planet. Below are the full sign description (yellow), sign group text (blue) and modality text (red). The sign can be overridden via dropdown if needed.

Chinese — zodiac animal, element and yin/yang calculated from birth year, with character description. Note: simplified calculation — for births in January or February check the exact Chinese New Year date.

Indian — a reference table showing the correspondence between Western signs, Indian (Vedic) signs and Chinese signs with their elements. The current patient's sign is highlighted.

Tab 5 — Profile

Step-by-step instructions for building a complete five elements and astrological profile for a patient. Explains the workflow from DOB entry through to syndrome identification.

Recommended workflow

• Ensure DOB is recorded on the patient record
• Click ☯ Elements → Profile tab to read the instructions
• Check Chinese sign element (Astrology → Chinese)
• Check Western sign element (Astrology → Western)
• Compare both with the Five Elements tab — adjust if needed
• Note the organ syndromes shown below the pentagon
• Record pulse findings on the Pulse History tab after each relevant session

First steps after installation

Before adding patients, configure the system in Setup:

• Setup → Practice — enter your practice name, address, therapy type and currency symbol. This information appears on letters and receipts.
• Setup → Locations — add your practice location(s). If you work across multiple sites, add each one here and set a default location per user.
• Setup → Users — add any additional practitioners or reception staff. Set their access level appropriately.
• Setup → Schedule — add your appointment types (e.g. New Patient 60 mins, Follow-up 30 mins) and treatment rooms.
• Setup → Value Lists — customise the occupation and therapy type dropdowns.

Recommended first-use order

• 1. Configure Setup as above
• 2. Add your GP contacts (Contacts → New Contact, type GP)
• 3. Add your first patient
• 4. Record baseline examination findings for that patient
• 5. Record their first session
• 6. Write a letter if needed

Changing your password

Go to Setup → Password. You'll need to enter your current password before setting a new one. Minimum 8 characters.

The welcome page serves two purposes — a public-facing introduction to CrystalSolutions for visitors who aren't logged in, and a daily practice dashboard for logged-in users. The two views are different: the public view shows the feature overview; the logged-in view shows live practice data.

Dashboard panes

The logged-in dashboard shows up to six collapsible panes — each only appears if there is data to show:

• 📌 Practice Noticeboard — the practice-wide note from Setup → Practice. Visible to all users. Edit it in Setup to leave notes for all staff: "Buy couch rolls", "Ring Blair re Thursday".
• 📝 Recent Activity — the 8 most recently added patients and sessions across the practice, with who added them and when. Useful for monitoring trial users or multi-practitioner activity.
• 🕐 Due for Review — patients who haven't been seen within the practice review period. Only shows if a review period is set in Setup. Click any name to go to their record; "all" link filters the patient list.
• 💊 Recent Medicines — medicines and remedies recorded in recent sessions, grouped by patient with the improvement rating shown as a green badge.
• 📋 Treatment Plans — active treatment plans with achieved/to-do counts and a progress bar. Links directly to each patient's plan.
• 👣 Podiatry Notes — patients with podiatry notes recorded, showing a preview and linking to their podiatry page.

Collapsible panes

Each pane has a small hide / show link in the top right. Click hide to collapse a pane — it stays collapsed on that device until you show it again. This is stored in your browser's local storage, so each device remembers its own settings independently.

The Modules section (the feature cards — Patients, Sessions, Audit etc.) also has a single hide/show toggle. Once you know the system, hide the modules to keep the dashboard clean.

The Design Philosophy card at the top has its own hide/show. New users should read it; experienced practitioners can hide it permanently.

Turning off the welcome screen

If you'd prefer to go straight to the patient list after login rather than seeing the dashboard, go to Setup → Practice and uncheck Welcome screen on/off. You'll land on the Patients list every time instead.

Public landing page

When someone visits the CrystalSolutions URL without being logged in, they see the public version of the welcome page — the feature overview, design philosophy and pricing. This is intentional: the URL can be shared as a product overview. The clinical dashboard is only visible after login.

Adding a new patient

Click + New Patient from the Patients list. The only required field is Surname — all other fields can be filled in later. After saving you'll be taken directly to the patient record.

Searching for patients

The search bar on the Patients list searches across: surname, forename, phone, mobile, email and postcode. You can also filter by status (New, Existing, Regular etc.) and by practice location.

Sorting the patient list

Click any column header to sort the patient list by that column — click again to reverse the order. An arrow (↑ ↓) shows the current sort. Available sorts:

• Name — alphabetical by surname (default)
• Status — group by New, Existing, Regular etc.
• Practitioner — all patients of a specific practitioner together
• Last Seen — most or least recently seen first
• Added — date the record was created, newest first — useful for monitoring recent additions during a trial or when a new practitioner joins

Review flags

If a review period is set in Setup → Practice, a 🕐 clock icon appears next to the Last Seen date for any patient who hasn't been seen within that period. Hovering shows "Due for review". The same patients appear in the Due for Review pane on the welcome dashboard and in Audit → Quick Searches.

The patient record — top strip

The coloured strip at the top of every patient record shows the key clinical facts at a glance:

• Name, DOB, age, sex — always visible
• Primary condition — the original presenting complaint, set once and rarely changed
• Therapy type and practice location
• Precautions — shown in bold red if recorded (allergies, pacemakers, anticoagulants etc.)
• Arrow buttons ↑ ↓ → — set the patient's current trajectory (improving, worsening, stable)
• Colour tag — for grouping patients in audit projects (see below)
• Priority star ★ — shown when Priority is ticked in Edit

Patient record tabs

• Details — contact information, GP, insurance, practice details, and the yellow notes field
• Clinical — presenting condition, precautions, past medical history, other therapists. Also shows a read-only summary of Page 3 fields (diagnosis, prognosis, medicine history, treatment history) if populated — each with an Edit link going straight to Page 3.
• Sessions — full treatment history, most recent first
• Examination — baseline examination findings, plus a read-only summary of Page 2 history fields and the pain map thumbnail
• Letters — all letters written for this patient
• Attachments — uploaded files (PDFs, images) linked to this patient

The three note types

The colour tag — audit and research tool

The colour dots in the patient top strip are a temporary grouping tool for audit work, not a permanent clinical indicator. For example:

• Search for all female patients aged 20–40 with neck conditions
• Set them all to Yellow using the colour tag
• Filter the patient list by Yellow to work with that cohort
• Clear the colour when your analysis is complete

Colours available: Green, Yellow, Red, Blue, Grey and Clear. They carry no fixed clinical meaning — you decide what each colour represents for a given project.

Primary condition vs session condition

The Primary Condition on the patient record is the original presenting complaint — it's set once at first contact and reflects why this person became your patient. It doesn't change when they come in with something different one week.

Each Session records its own primary and secondary condition for that visit. Secondary conditions and evolving presentations are captured in the yellow notes and per-session records.

Save button at the top

Both the new session and edit session forms have a Save Session button in the page header — right next to the patient name. No need to scroll to the bottom of a long form just to save, especially useful on mobile or when you only need to update a few fields.

Collapsible sections

The Examination Findings and Fee cards each have a small hide/show link in their title bar. If you rarely use examination findings in sessions, hide that section — it stays hidden on that device until you show it again (stored in browser local storage). This keeps the form compact for quick end-of-day data entry.

Recording a session

Sessions are individual treatment appointments. Add a new session from the patient record (+ Session button) or from the Sessions list. Sessions require Medium Level access or above — reception staff can view sessions but cannot add or edit them.

Therapy type default

The Therapy Type field on a new session pre-fills automatically from the practice default set in Setup → Practice. You can override it for any individual session. This saves time for single-discipline practices where every session is the same therapy type.

Podiatry from within a session

The Examination Findings card on the session form has a 👣 Podiatry button in the top right. This opens the patient's podiatry page in a new tab so you can record podiatry findings alongside the session — without losing your place in the session form.

Session fields

• Date — defaults to today
• Primary condition — what you treated this visit
• Secondary condition — any concurrent presenting complaint
• State — Acute, Sub-acute, or Chronic
• Nerve radiation — free text description of any radiation pattern
• SLR — straight leg raise result in degrees (left and right)
• Worse / Better — aggravating and relieving factors
• Accident — whether trauma is involved and how long ago
• Treatments — what techniques you used
• Treatment notes — free text clinical notes
• Improvement — patient's reported improvement level
• Maintenance — whether this is a maintenance visit
• Medicines — standard medications, supplements, herbs, homeopathics
• Fee and payment — amount, paid status, payment method

Examination findings in sessions

The session form includes all 7 examination tabs. You only need to record what has changed from the baseline — the baseline findings are shown as hints (blue dots). If nothing has changed neurologically, leave the Neurological tab blank.

The session view shows changed findings highlighted in blue with a "new" badge, making it easy to see what was different at that visit compared to the patient's baseline.

Baseline vs session findings

Examination findings work on a two-tier system:

• Baseline — recorded on the patient record, updated only when there is a significant change to the overall clinical picture. This is the reference against which future sessions are compared.
• Session changes — recorded per-session, only when findings differ from the baseline. If cranial nerve examination is normal and unchanged, leave it blank.

The 7 examination tabs

Audit trail

The patient examination page shows the full history of session-level changes with dates, each linking back to the original session record. This provides a longitudinal record of how the clinical picture has evolved over time.

History and pain map on the Examination tab

The Examination tab on the patient record also shows a read-only summary of the Page 2 case history fields — secondary conditions, condition duration, accident/RTA, PMH & cranial text, and the examination findings mosaic. The pain map (front and back body diagram) appears as a compact thumbnail alongside these fields, with only the painted zones coloured. All fields link back to Page 2 for editing.

Podiatry & Chiropody

The Examination tab has a 👣 Podiatry button in the top right of the baseline findings card. This opens a dedicated podiatry page with six finding groups — General, Forefoot, Toe, Ankle, Midfoot and Hindfoot — each with a dropdown value list. Select Left / Right / Both, choose a finding and click → to append to the podiatry notes field. Podiatry notes are stored separately from the baseline examination findings and shown in their own card at the bottom of the Examination tab when recorded.

Views

• Week view (default) — a time grid from your diary start to end time, with one column per day. Click any empty slot to book an appointment.
• Day view — single day, same grid. Click a day number in week view to jump to day view for that date.
• Month view — calendar overview. Shows up to 3 appointments per day. Click a day to go to day view.

Booking an appointment

Click any empty time slot or the + New Appointment button. The booking form lets you set:

• Patient — select from your patient list
• Appointment type — automatically sets the duration (configurable in Setup → Schedule)
• Duration — overridable per booking
• Room / Resource — if you have multiple treatment rooms
• Notes — clinical or admin notes for this appointment
• Special needs — downstairs room required, extra time, latex allergy etc. Shown prominently in orange.
• Confirmed — tick when patient has confirmed attendance
• Send reminder — flag for reminder (reminder sending infrastructure will be added in a future version)
• Recurring — set a repeat pattern (weekly, fortnightly, monthly) with an end date

Entry types

• Appointment — patient booking
• Blocked — unavailable time (grey)
• Admin — administration time
• Holiday — practitioner holiday or absence

Viewing other practitioners' diaries

Use the practitioner dropdown at the top of the schedule to switch between diaries. Administrators can view all diaries. The Side by side button (admin only) shows all practitioners in columns simultaneously.

Editing another practitioner's appointments

If you try to edit an appointment belonging to another practitioner, you will be asked to enter that practitioner's password. This prevents accidental changes to someone else's diary while still allowing reception staff to make bookings on behalf of practitioners.

Marking attendance

Click an appointment to open the popup, then click ✓ Attended to mark the patient as attended. This can be done by reception at the time of the appointment. Attended appointments are shown with reduced opacity.

Diary settings

Click ⚙ Diary Settings to configure your personal diary preferences:

• Day start and end time
• Appointment slot duration (15, 20, 30, 45, 60, 90 mins)
• Show or hide weekends

Each practitioner has their own diary settings. Administrators can set settings for any user.

Income tab

Records payments received from patients. Each receipt records: date, patient (optional), amount, payment method, status (stored/pending/void), practitioner and notes.

Income receipts can be added by reception staff (Low Level access). Only Medium Level and above can add expenditure or delete records.

Expenditure tab

Records business outgoings. Expense types include: courses, equipment, materials, postage, rent, software, stationery and more. Each expense records: date, type, recipient, amount, payment method, and optional tax rate.

The Debit / Credit field distinguishes outgoing payments from refunds received.

Filtering

Filter by year and month. The summary bar at the top always shows the filtered totals for Income, Expenditure and Net — useful for monthly reconciliation and annual returns.

Payment methods

Cash, Cheque, Debit Card, Credit Card, BACS, Insurance, Trade, Unpaid, Gratis.

Writing a letter

Open a patient record and click ✉ Letter. Choose a template or start blank. The letter is pre-populated with patient and practice details via merge variables.

Merge variables

Templates use {{double curly braces}} for merge fields. Available variables:

Starter templates

• Appointment Reminder — includes appointment date/time placeholders
• Discharge Letter to Patient
• GP Referral Letter — includes patient details, presenting complaint, examination findings placeholder
• GP Letter — Treatment Report
• Dietary Advice Letter
• General Letter — blank template

Audit trail

Every saved letter is stored against the patient record with the date, recipient, subject and the name of who wrote it. Letters appear in the Letters tab of the patient record and in the main Letters list.

The Documents module stores two types of document: Practice Documents (contracts, policies, GDPR notices — not linked to any patient) and Patient Documents (consent forms, insurance authorisations, GDPR sign-offs — stored directly against a patient record).

Creating a patient document

Open a patient record and click 📄 Document in the quick-action strip. Choose a template or start blank. The document is pre-populated with patient and practice details via merge variables. Give it a name, optionally record a signed date, edit the body, and save.

Creating a practice document

Go to Documents in the main navigation, select the Practice Docs tab, and click + New Practice Document. Choose a template (e.g. Associate Contract, GDPR Privacy Notice) or start blank. Practice documents are not linked to any patient — they are available to all staff to view and print.

Merge variables

Templates use {{double curly braces}} for merge fields. Variables are merged automatically when you choose a template. You can also click any variable chip to insert it at the cursor position while editing.

Starter templates

• Associate Contractor Agreement — self-employed practitioner contract with commission tiers
• GDPR Privacy Notice — patient-facing data protection notice
• Patient Consent Form — treatment consent with signature line
• Cancellation Policy — 24-hour notice policy
• Insurance Authorisation Letter — patient-addressed letter for insurer use

Signed date

Patient documents have an optional Signed Date field. Once recorded, the date shows in green in the Documents tab — useful for tracking which patients have signed their consent form. Unsigned documents show a dash.

Printing and PDF

Open any document and click Print / PDF. The document renders with a practice letterhead (practice name and address from Setup) and prints cleanly — use your browser's "Save as PDF" option to generate a PDF copy.

Three-tab layout

The Documents page has three tabs:

• Practice Docs — contracts, policies and practice-level documents
• Patient Docs — all patient documents across the practice, with search by patient or document name
• Templates — manage the document template library (Admin only)

Access control

Recording CPD

Each entry records: date, category, title, provider, hours, whether a certificate is held, notes and a reflection. The reflection field is required by most UK regulatory bodies for audit purposes.

CPD categories

• Course / Workshop
• Conference / Seminar
• Webinar / Online Learning
• Reading / Research
• Supervision / Mentoring
• Peer Review
• Teaching / Presenting
• Clinical Observation
• Self-directed Study
• Other

Printing for your regulatory body

Click Print / Export to open a clean print-ready version of your CPD log. This opens in a new tab and triggers the print dialog automatically. It includes all entries for the selected year, your reflection notes, and a total hours summary showing verified vs unverified hours.

Filter by year before printing to produce your annual CPD return. The GOsC and other regulatory bodies typically require a minimum of 30 hours per year.

Multiple practitioners

Each practitioner sees only their own CPD log. Administrators can switch between practitioners using the dropdown at the top of the CPD page.

What contacts are for

Contacts stores GPs, specialists, referrers, associates and other healthcare providers. A patient can have a GP linked to their record — when you write a GP referral letter, the GP's name and address auto-populate from this contact record.

Contact types

GP, Specialist, Physiotherapist, Osteopath, Chiropractor, Acupuncturist, Herbalist, Homeopath, Naturopath, Counsellor, Podiatrist, Reflexologist, Aromatherapist, Insurer, Solicitor, Associate, Supplier, Staff, Reception, Other.

Dual address

Each contact can have two addresses — typically a surgery/practice address (A) and a home address (B). The secondary address is hidden by default and expands when needed.

Linked patients

When viewing a GP contact record, all patients who have that GP linked to their record are listed at the bottom — useful for managing practice populations and referral relationships.

What the stock module does

The stock module tracks dispensary products and practice supplies — quantities in stock, reorder levels, purchase and sale transactions, and supplier links. Low stock items appear as a warning on the welcome dashboard.

Two tabs

Products & Remedies — things you sell or dispense to patients: supplements, homeopathic remedies, herbal preparations, and other saleable items.

Practice Supplies — consumables you use but don't sell: couch roll, gloves, equipment, office supplies.

Adding a product

Click + Add Item on the relevant tab. Fill in the name, category, unit, cost price, sale price, and reorder level. Link a supplier if you have one set up in Contacts.

The Unit field should contain a word describing the unit of measure — not a quantity. For example:

• Arnica 30c (Products & Remedies) → Unit: bottles
• Couch roll (Practice Supplies) → Unit: rolls
• Needles → Unit: boxes or each

Setting opening stock

There is no opening stock field on the product form — stock levels are built entirely from transactions. After adding a new product, set your opening balance like this:

1. Add the product with the correct unit label, prices and reorder level
2. Click + Stock on the product card
3. Choose type Purchase, enter your current stock quantity and today's date
4. Save — the stock level updates immediately

This establishes your opening balance and appears correctly in the transaction history. The online demo has working examples of both a remedy (Arnica) and a practice supply (Couch rolls) if you want to see how it should look.

Recording stock movements

Click + Stock on any product card to record a transaction. Four types are available:

• Purchase — stock received from a supplier. Increases stock qty.
• Sale to patient — sold directly from the dispensary. Decreases stock qty.
• Adjustment — stock count correction. Enter a positive number to increase (e.g. you found extra stock) or a negative number to decrease (e.g. correcting a counting error). Use this when the change doesn't fit neatly into purchase, sale or write-off.
• Write off — expired or damaged stock. Always decreases stock qty — enter the quantity to remove as a positive number.

Products sold during a session

When editing a session, a Products Sold / Used card appears below Medications and above Fee. Select a product from the dropdown — it shows current stock levels — enter the quantity, and the price auto-fills from the product's sale price (which you can override). Stock decrements automatically when you save the session. If you edit and re-save, the stock is recalculated correctly.

Low stock alert

Any active product whose stock quantity is at or below its reorder level appears in the amber ⚠ Low Stock pane on the welcome dashboard. Click Manage stock → to go directly to the stock page. The alert only fires if a reorder level greater than zero has been set.

Transaction history

Click History on any product card to see a full log of all stock movements — purchases, sales, adjustments and write-offs — with date, quantity, price and the patient if a session sale was linked. Use the From / To date filter to narrow to a period, then click Print / PDF to print or save as PDF from your browser. A totals row at the bottom shows units in, units out, net movement and total value for the filtered period.

Inactive products

Products you no longer stock can be deactivated (Administrator only) rather than deleted. Inactive products are hidden by default but their transaction history is preserved. Click Show inactive to view them.

Practice tab

Sets the practice name, address, default practitioner, therapy type, currency symbol, tax rate, date format, review period and the practice-wide noticeboard. Also controls hover tips and the welcome screen.

Practice Noticeboard

The 📌 Practice Noticeboard field (in the Practice tab) shows its content on the welcome dashboard for all logged-in users. Use it for day-to-day practice reminders: "Order couch rolls", "Ring Blair re Thursday", "Parking suspended 15th–17th". It's not patient-specific — it's a shared practice whiteboard visible the moment anyone logs in.

Hover tips & welcome screen

Two checkboxes sit side by side in the Practice tab:

• Hover tips on/off — button tooltips appear when you hover over buttons. Useful for new users; turn off once your team knows the system.
• Welcome screen on/off — controls whether the welcome dashboard appears after login. Turn off to go straight to the patient list. The welcome screen can also be used as a permanent practice dashboard — collapsing the modules and philosophy sections leaves just the clinical panes.

Locked tabs

Users who don't have access to certain Setup tabs (e.g. Medium Level users who can't access Locations, Value Lists etc.) still see those tabs in the Setup tab bar — but they're greyed out with a 🔒 lock icon. Hovering shows which access level is required. This lets lower-access users see what the system is capable of without being able to change restricted settings.

Review Period

Set a default review period (e.g. 6 Months, 12 Months) to flag patients who haven't been seen within that time. Once set, a 🕐 review flag appears in four places:

• Patient list — a 🕐 clock icon next to the Last Seen date for overdue patients
• Patient record — a yellow banner at the top showing how long since their last visit, with a quick + Book Session button
• Welcome dashboard — a "Due for Review" pane showing the most overdue patients
• Audit page — a "Due for Review" quick search button that shows all overdue patients in the patient list

The review message (optional) appears in the patient record banner — useful for a standard reminder such as "Consider booking a maintenance appointment."

Password tab

Change your own login password. Requires your current password. Minimum 8 characters.

Locations tab

Add and manage practice locations. Each location has a full address, phone and email. The default location table at the bottom lets you set which location each user is based at — this pre-selects the location when adding patients and sessions.

Schedule tab

Manage appointment types (name, default duration, colour) and treatment rooms/resources. Changes here affect all practitioners. The colour assigned to an appointment type is used in the diary grid.

Colour Labels tab

Label each of the five audit colours to describe what cohort they currently represent. For example: Green = "Female patients, low back, under 45", Red = "Maintenance patients due review". Labels appear as tooltips on colour dots throughout the system — on patient records, the Audit page and Statistics. Clear the label when the audit project is complete.

Locations, Schedule, Colour Labels tabs

Available to High Level and Administrator. Locations manages practice sites. Schedule manages appointment types and treatment rooms. Colour Labels sets the meaning of each audit colour tag.

Value Lists tab

Available to High Level and Administrator. Shows all dropdown lists used across the system with an index at the top. High Level users can add new values to any list. Only Administrators can delete values — this prevents one practitioner accidentally removing entries needed by another.

Users tab

Administrator only. Create and manage user accounts, access levels and enabled status. You cannot delete your own account or reduce your own access level.

CrystalSolutions requires a licence key to operate without restrictions. Keys are in the format CS-XXXX-XXXX-XXXX-XXXX and are provided when you purchase the software.

Activating your licence

Go to Setup → Licence (Administrator only). Enter your licence key, name and email address, then click Activate. The licence is stored in the database and applies to the whole installation — all users benefit from a single activation.

Without a licence

An unactivated installation works fully but is limited to 10 patient records — enough to verify the system works for your practice before committing to purchase. All existing records remain fully accessible and editable — the limit only prevents adding new patients beyond 10. A banner appears at the top of every page while in trial mode.

Purchasing a licence

Licences are available at soul-trade.com/software.html — £85 one-off, no subscription. Once you have your key, go to Setup → Licence and activate it to unlock unlimited use.

Locked tabs in Setup

Non-Administrator users see the Licence tab in Setup as a greyed-out 🔒 locked tab. This is expected — only Administrators can manage the licence. High Level and Medium Level users can see it exists but cannot access it.

The licence key format

Keys encode the product (CrystalSolutions or PraxisClinic), edition (Standard or Pro) and purchase date. They are cryptographically signed and verified offline — no internet connection is required for activation or verification.

Moving to new hardware

Your licence key can be activated on any number of installations you own — there is no machine binding. If you move CrystalSolutions to a new server, simply activate the same key in Setup → Licence on the new installation.

Import/Export is in the main navigation. High Level access or above required.

Export tab

Five CSV export buttons — Patients, Sessions, Income, Expenditure and Contacts. Each downloads a UTF-8 CSV file that opens correctly in Excel, Numbers or any spreadsheet. Exports include all fields including clinical data from Pages 2 and 3.

Import tab

Import patients from any CSV file — FileMaker export, another practice management system, or a spreadsheet. Two steps:

• Step 1 — Upload your CSV file. A preview of the first few rows is shown.
• Step 2 — Map each column to the correct field. Common field names (including FileMaker field names) are auto-detected. Columns you don't need can be skipped.

Rows without a surname are skipped. All other validation errors are reported after the import with a count of imported vs skipped records.

Patient Record Export tab

Export a single patient's complete record as a printable document. Select the patient and which sections to include (contact details, clinical, Pages 2 and 3, sessions, letters, attachments). Opens as a clean print-ready page — use Print → Save as PDF in your browser to generate a PDF.

The 📤 Export button on every patient record goes directly here. Useful for subject access requests, referrals, or patient handover.

The four access levels

Diary access

All access levels can view the schedule and book appointments. Editing another practitioner's existing appointment requires entering that practitioner's password — this prevents accidental changes while still allowing reception to manage bookings.

The Setup Wizard (setup_wizard.php) is included in every CrystalSolutions distribution. It installs the system in your browser in five steps — no command line, no manual file editing. The same wizard works identically on Synology NAS, Windows (XAMPP), Mac (MAMP), Raspberry Pi and Linux.

Before running the wizard

• Copy all CrystalSolutions files to your web server folder (see the relevant installation guide for your platform)
• Create an empty MySQL / MariaDB database and a database user with full privileges on it — do this in phpMyAdmin or via the command line before starting the wizard
• Leave config.php as-is — the wizard will overwrite it with your settings

Running the wizard

Open a browser and go to http://[your-server]/cspractice/setup_wizard.php. The wizard walks through five steps:

• Step 1 — Pre-flight checks — confirms PHP version, required extensions, folder permissions and that the sql/ folder is present. Any failed check is shown with a clear explanation.
• Step 2 — Database — enter your database host, name, username and password. The wizard tests the connection live and won't proceed if it can't connect.
• Step 3 — Practice details — practice name, default therapy type, currency and the base URL (auto-guessed from your server address — check it carefully).
• Step 4 — Admin account — create your Administrator login: username, display name and password (minimum 8 characters).
• Step 5 — Install — shows a summary for review, then runs all database migrations, saves practice settings, creates your admin user and writes config.php. A full installation log is shown.

After installation

When the wizard completes you'll see a Go to CrystalSolutions → button. Click it and log in with the admin account you just created.

If config.php can't be written

On some servers (particularly NAS devices with strict folder permissions), the wizard may not be able to write config.php automatically. If you see this error, create config.php manually — drag it into the web folder via Finder or File Station. The simple installer (cs_install.php) is often easier on NAS devices as it detects an existing config.php and skips the write step automatically.

A complete config.php requires all constants including APP_ROOT, DB_CHARSET, DATE_DISPLAY, DATE_SHORT, DATE_DB, DEMO_MODE and DEV_MODE — a partial file will cause a white page. See the installation guide for the full template.

Re-running the wizard

The wizard is blocked if config.php already contains real database credentials — a security measure to prevent accidental reinstallation. To re-run it, replace config.php with the original placeholder version from the distribution zip.

Why a NAS?

Many small practices already have a Synology or QNAP NAS for file storage and backups. These devices run 24/7, consume very little power, and most modern models support PHP and MariaDB — making them ideal CrystalSolutions servers. No additional hardware needed.

Requirements

• DSM 7.x (most Synology NAS devices from 2018 onwards)
• At least 1GB RAM (2GB recommended)
• Internet access during package installation

Step 1 — Install Web Station

Open Package Center → search for Web Station → Install. Web Station provides Apache/Nginx and PHP support on your NAS.

Step 2 — Install and configure PHP 8

In Web Station → Script Language Settings → click your PHP 8.2 user defined profile → Extensions tab. Enable: pdo_mysql, mysqli, gd. These are the key ones needed for CrystalSolutions to run. (pdo, mbstring and fileinfo may not appear in the list — that's fine, they are built into Synology's PHP and don't need enabling separately. We couldn't add them and installation worked correctly without them.)

Step 3 — Install MariaDB 10

Package Center → search MariaDB 10 → Install. Set a strong root password when prompted — write it down. MariaDB is fully MySQL-compatible and works with CrystalSolutions without any changes.

Step 4 — Install phpMyAdmin (recommended)

Package Center → search phpMyAdmin → Install. Use this to create the database and user before running the setup wizard.

Step 5 — Create the database

Open phpMyAdmin → log in as root → click New in the left panel → name the database crystalsolutions → select utf8mb4_unicode_ci collation → Create. Then create a database user with full privileges on that database.

Step 6 — Create a web folder

In File Station, navigate to the web shared folder → create a new folder called cspractice. The full path will be /volume1/web/cspractice.

Step 7 — Configure Web Station

Web Station → Web Service Portal → Create → choose your PHP 8 profile → set Document Root to /volume1/web/cspractice. Note the port (usually 80 or 8080).

Step 8 — Upload CrystalSolutions files

Use File Station or an FTP client (Fetch, Cyberduck, FileZilla) to copy all CrystalSolutions files into /volume1/web/cspractice.

Step 9 — Run the Setup Wizard

From any browser on your network, open http://[nas-ip-address]/cspractice/setup_wizard.php. Follow the five steps. The base URL will typically be http://192.168.x.x/cspractice — check your NAS IP address in DSM → Control Panel → Network.

Step 10 — Delete the wizard and log in

Delete setup_wizard.php from File Station. Then open http://[nas-ip]/cspractice and log in with the admin account you created.

File permissions

If file attachments aren't working, the attachments/ folder may need write permissions. In File Station, right-click the attachments folder → Properties → Permissions → ensure the web server user (usually http) has read/write access.

Permissions greyed out? They are being inherited from the parent folder. Fix: File Station → right-click the folder → Properties → Permission → click Advanced Options → select Make inherited permissions explicit → click Save. The checkboxes will now be editable. This applies to both the attachments/ folder and the main cspractice/ folder if the installer cannot write config.php.

Automated backups

Use Hyper Backup (available in Package Center) to schedule nightly backups of the MariaDB database. Back up to a USB drive, another NAS, or a Synology C2 cloud destination. Include the cspractice web folder to back up attachments.

SET FOREIGN_KEY_CHECKS = 0;
DROP TABLE IF EXISTS sessions;
DROP TABLE IF EXISTS appointments;
DROP TABLE IF EXISTS letters;
DROP TABLE IF EXISTS attachments;
DROP TABLE IF EXISTS treatment_plans;
DROP TABLE IF EXISTS treatment_plan_items;
DROP TABLE IF EXISTS cpd_entries;
DROP TABLE IF EXISTS diary_settings;
DROP TABLE IF EXISTS accounts_income;
DROP TABLE IF EXISTS accounts_expenditure;
DROP TABLE IF EXISTS value_lists;
DROP TABLE IF EXISTS processed_txns;
DROP TABLE IF EXISTS contacts;
DROP TABLE IF EXISTS patients;
DROP TABLE IF EXISTS practices;
DROP TABLE IF EXISTS users;
DROP TABLE IF EXISTS settings;
SET FOREIGN_KEY_CHECKS = 1;

Why a Raspberry Pi?

A Raspberry Pi 4 or Pi 5 is the ideal practice server for CrystalSolutions:

• Costs around £55–£80 new (Pi 4 2GB or Pi 5 2GB)
• About the size of a credit card — fits behind a monitor, in a drawer, or in a cupboard
• Completely silent — no fan, no noise
• Uses only 3–5 watts — costs pennies per year to run 24/7
• Runs Linux (Raspberry Pi OS) — stable, secure, free
• Restarts automatically after power cuts

What you need

• Raspberry Pi 4 or Pi 5 (2GB RAM minimum, 4GB recommended)
• MicroSD card — 16GB minimum, 32GB recommended (Class 10 or better)
• USB-C power supply (official Pi power supply recommended)
• A network cable (Ethernet) or WiFi connection to your practice router
• A keyboard and monitor for initial setup only — not needed afterwards

Step 1 — Install Raspberry Pi OS

On any computer, download the Raspberry Pi Imager from raspberrypi.com/software. Insert your MicroSD card, open the Imager, choose Raspberry Pi OS Lite (64-bit) as the operating system, select your MicroSD card, and click Write.

Before writing, click the ⚙ settings icon to:

• Set a hostname (e.g. cspractice)
• Enable SSH
• Set a username and password (remember these)
• Configure your WiFi if not using Ethernet

Step 2 — First boot and connect

Insert the MicroSD into the Pi, connect power and Ethernet, and wait 2 minutes for first boot. From any other computer on the same network, open Terminal (Mac) or Command Prompt (Windows) and type:

ssh pi@cspractice.local

Enter your password when prompted. You are now connected to the Pi.

Step 3 — Update and install the stack

Copy and paste these commands one at a time. Wait for each to finish before running the next:

sudo apt update && sudo apt upgrade -y
sudo apt install -y apache2 php php-mysql php-mbstring mysql-server
sudo systemctl enable apache2 mysql
sudo systemctl start apache2 mysql

Step 4 — Secure MySQL and create the database

sudo mysql_secure_installation

Answer Yes to all questions and set a root password. Then:

sudo mysql -u root -p
CREATE DATABASE crystalsolutions CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'csuser'@'localhost' IDENTIFIED BY 'choose-a-strong-password';
GRANT ALL PRIVILEGES ON crystalsolutions.* TO 'csuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 5 — Install CrystalSolutions

sudo mkdir -p /var/www/html/cspractice
sudo chown -R pi:pi /var/www/html/cspractice

Copy the CrystalSolutions files into /var/www/html/cspractice/ using a tool like FileZilla (SFTP, free) or the scp command. Edit config.php with your database credentials.

Step 6 — Enable mod_rewrite

sudo a2enmod rewrite
sudo nano /etc/apache2/sites-available/000-default.conf

Find the <Directory /var/www/html> section and change AllowOverride None to AllowOverride All. Save with Ctrl+O, exit with Ctrl+X, then:

sudo systemctl restart apache2

Step 7 — Run the Setup Wizard

From any browser on your network, open http://[pi-ip-address]/cspractice/setup_wizard.php and follow the five steps. The wizard creates the database tables, saves your practice settings, creates your admin user and writes config.php automatically. See the Setup Wizard section for full details.

If you prefer to run SQL migrations manually, install Adminer:

sudo wget -O /var/www/html/adminer.php https://www.adminer.org/latest.php

Visit http://[pi-ip]/adminer.php, log in and run the SQL files from the sql/ folder in order.

Step 8 — Find your Pi's IP address

hostname -I

This shows your Pi's IP address (e.g. 192.168.1.50). Set it as a static IP in your router settings. CrystalSolutions is then accessible from any device on your network at:

http://192.168.1.50/cspractice

Automated database backups

nano ~/backup-cs.sh

Paste this content:

#!/bin/bash
DATE=$(date +%Y-%m-%d)
BACKUP_DIR="/home/pi/backups"
mkdir -p "$BACKUP_DIR"
mysqldump -u csuser -p'your-password' crystalsolutions \
  > "$BACKUP_DIR/crystalsolutions-$DATE.sql"
find "$BACKUP_DIR" -name "*.sql" -mtime +30 -delete

chmod +x ~/backup-cs.sh
crontab -e
# Add this line:
0 2 * * * /home/pi/backup-cs.sh

Remote access with Tailscale (optional)

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Install Tailscale on the Pi and on each device that needs remote access. Sign in with the same account. The Pi gets a fixed Tailscale IP accessible from anywhere — perfect for home visits or a second site.

Recommended hardware

Any Mac Mini (2018 or later) makes an excellent practice server. The 2023 M2 Mini is ideal — fast, silent, uses only 6–12W, and will last many years. For a dedicated server, 8GB RAM and 256GB SSD is sufficient for a small practice.

Step 1 — Install Homebrew

Homebrew is the macOS package manager. Open Terminal (Applications → Utilities → Terminal) and paste:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Follow the prompts. On Apple Silicon Macs (M1/M2/M3) it installs to /opt/homebrew. On Intel Macs it installs to /usr/local.

Step 2 — Install PHP, MySQL and Caddy

brew install php mysql caddy

This installs PHP 8.3, MySQL 8, and Caddy (a modern web server that handles SSL automatically).

Step 3 — Start MySQL and set a root password

brew services start mysql
mysql_secure_installation

Follow the prompts to set a root password. Choose Yes to all security questions.

Step 4 — Create the database

mysql -u root -p
CREATE DATABASE crystalsolutions CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'csuser'@'localhost' IDENTIFIED BY 'choose-a-strong-password';
GRANT ALL PRIVILEGES ON crystalsolutions.* TO 'csuser'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Step 5 — Install CrystalSolutions

Create the web root folder and copy the CrystalSolutions files into it:

mkdir -p /Users/Shared/www/cspractice
# Copy the CrystalSolutions files into /Users/Shared/www/cspractice/
# Edit config.php with your database credentials

Step 6 — Configure Caddy

Create a file called Caddyfile in your home folder:

:80 {
    root * /Users/Shared/www
    php_fastcgi unix//opt/homebrew/var/run/php-fpm.sock
    file_server
    encode gzip
}

Then start Caddy and PHP-FPM:

brew services start php
brew services start caddy

Step 7 — Find your local IP address

Go to System Settings → Network → your WiFi connection → Details. Note the IP address (e.g. 192.168.1.50). Set it to be static in your router settings so it never changes.

CrystalSolutions is now accessible from any device on your network at:
http://192.168.1.50/cspractice

Step 8 — Run the Setup Wizard

From any browser on your network, open http://[mac-ip-address]/cspractice/setup_wizard.php and follow the five steps. See the Setup Wizard section for full details. Delete the wizard file after installation.

To run SQL migrations manually instead, install Adminer:

curl -o /Users/Shared/www/adminer.php https://www.adminer.org/latest.php

Visit http://[mac-ip]/adminer.php, log in, select the crystalsolutions database, and run each SQL file from the sql/ folder in order.

Step 9 — Auto-start on boot

The brew services command already configures PHP, MySQL and Caddy to start automatically when the Mac boots. Make sure the Mac Mini is set to restart automatically after a power failure: System Settings → Energy → Options → Start up automatically after a power failure.

Remote access with Tailscale (optional)

To access the system from outside the practice (home visits, second site, working from home):

• Download Tailscale from tailscale.com — free for personal use
• Install on the Mac Mini server and on each device that needs remote access
• Sign in with the same Tailscale account on all devices
• The Mac Mini gets a fixed Tailscale IP (e.g. 100.64.x.x) — use this to access CrystalSolutions from anywhere

Automated database backups

Create a backup script. Open Terminal and create the file:

nano ~/backup-cs.sh

Paste this content:

#!/bin/bash
DATE=$(date +%Y-%m-%d)
BACKUP_DIR="/Users/Shared/backups"
mkdir -p "$BACKUP_DIR"
/opt/homebrew/bin/mysqldump -u csuser -p'your-password' crystalsolutions \
  > "$BACKUP_DIR/crystalsolutions-$DATE.sql"
# Keep only last 30 days
find "$BACKUP_DIR" -name "*.sql" -mtime +30 -delete

Make it executable and schedule it daily at 2am:

chmod +x ~/backup-cs.sh
crontab -e
# Add this line:
0 2 * * * /Users/your-username/backup-cs.sh

Time Machine will then back up these SQL dump files along with everything else. Test your backup by restoring a dump file to a test database.

Just testing? Use MAMP instead

If you want to try CrystalSolutions on your Mac before committing to a full installation, MAMP is much simpler — no Terminal, no Homebrew, no configuration files.

1. Download MAMP (free version) from mamp.info → install and open
2. Click Start — Apache and MySQL indicators turn green
3. Copy all CrystalSolutions files to /Applications/MAMP/htdocs/cspractice/
4. Open phpMyAdmin at http://localhost:8888/phpmyadmin → create database crystalsolutions with collation utf8mb4_unicode_ci
5. Visit http://localhost:8888/cspractice/cs_install.php — use localhost as host, root as username, root as password (MAMP default)
6. Delete cs_install.php after installation

MAMP is ideal for testing and development. For a permanent practice server, use the Homebrew/Caddy setup above — it runs as a proper background service and starts automatically on boot.

Recommended hardware

Any Windows PC or laptop with Windows 10 or 11 will work. For a dedicated practice server, a used mini-PC (Beelink, Intel NUC, or similar) is ideal — compact, quiet and power-efficient. Budget £100–£200 for a used unit with 8GB RAM and an SSD.

Option A — XAMPP (easiest, recommended for beginners)

XAMPP bundles Apache, PHP and MySQL into a single installer with a graphical control panel. It's the quickest way to get running.

1. Download and install XAMPP

Download from apachefriends.org — choose the PHP 8.3 version. Run the installer, accepting defaults. Install to C:\xampp.

2. Start Apache and MySQL

Open the XAMPP Control Panel (Start Menu → XAMPP Control Panel). Click Start next to Apache and MySQL. Set both to start automatically by clicking the checkbox on the left.

3. Create the database

Open a browser and go to http://localhost/phpmyadmin. Click New in the left panel, name the database crystalsolutions, set collation to utf8mb4_unicode_ci, and click Create.

Then go to User Accounts → Add user account. Create a user csuser with host localhost, set a strong password, and tick Grant all privileges on crystalsolutions.

4. Install CrystalSolutions

Copy the CrystalSolutions files into C:\xampp\htdocs\cspractice\. Leave config.php as-is — the Setup Wizard will configure it.

5. Run the Setup Wizard

Open a browser and go to http://localhost/cspractice/setup_wizard.php. Follow the five steps — the wizard creates all database tables, saves your practice settings, creates your admin user and writes config.php. See the Setup Wizard section for full details. Delete the wizard file after installation.

To run SQL migrations manually instead: in phpMyAdmin, select the crystalsolutions database → SQL tab → run each file from the sql/ folder in order.

6. Access from other devices

Find your local IP: open Command Prompt (Win+R → cmd) and type ipconfig. Note the IPv4 address (e.g. 192.168.1.60). Set it as a static IP in your router.

Windows Firewall may block access from other devices. Go to Windows Defender Firewall → Allow an app → allow Apache HTTP Server for private networks.

CrystalSolutions is then accessible at: http://192.168.1.60/cspractice

Option B — Laragon (more powerful, cleaner)

Laragon (laragon.dev) is a modern alternative to XAMPP — faster, cleaner, and easier to manage multiple PHP versions. Download the full version, install it, and follow the same steps as XAMPP above. The web root is C:\laragon\www\.

Enabling mod_rewrite (Apache)

CrystalSolutions uses .htaccess for URL handling. In XAMPP, open C:\xampp\apache\conf\httpd.conf in Notepad, find the line #LoadModule rewrite_module and remove the #. Also find AllowOverride None for the htdocs directory and change it to AllowOverride All. Restart Apache.

Remote access with Tailscale (optional)

Same as Mac — download Tailscale from tailscale.com, install on the server PC and on each device that needs remote access, sign in with the same account. The server gets a fixed Tailscale IP accessible from anywhere.

Automated database backups

Create a batch file for daily backups. Open Notepad and save as backup-cs.bat:

@echo off
SET DATE=%date:~10,4%-%date:~4,2%-%date:~7,2%
SET BACKUP=C:\backups\crystalsolutions-%DATE%.sql
IF NOT EXIST C:\backups mkdir C:\backups
"C:\xampp\mysql\bin\mysqldump.exe" -u csuser -pyour-password crystalsolutions > %BACKUP%

Schedule it: open Task Scheduler (Start → Task Scheduler), create a Basic Task, set it to run daily at 2:00 AM, and point it to your batch file. Copy the backup folder to an external drive or cloud storage regularly.

Windows-specific security notes

• Set a Windows login password on the server PC — do not use auto-login
• Enable Windows Update and keep it current
• Change the MySQL root password from the default (XAMPP ships with a blank root password — fix this immediately in phpMyAdmin → User Accounts)
• Consider enabling BitLocker drive encryption (available on Windows 10/11 Pro) to protect patient data if the machine is stolen

Useful free tools for Windows

• HeidiSQL — excellent MySQL GUI for Windows, easier than phpMyAdmin for some tasks
• Notepad++ — for editing config.php and other files
• WinSCP — if you ever need to transfer files to a remote server
• Tailscale — secure remote access without port forwarding

Just testing? Use MAMP instead

If you want to try CrystalSolutions on your Mac before committing to a full installation, MAMP is much simpler — no Terminal, no Homebrew, no configuration files.

1. Download MAMP (free version) from mamp.info → install and open
2. Click Start — Apache and MySQL indicators turn green
3. Copy all CrystalSolutions files to /Applications/MAMP/htdocs/cspractice/
4. Open phpMyAdmin at http://localhost:8888/phpmyadmin → create database crystalsolutions with collation utf8mb4_unicode_ci
5. Visit http://localhost:8888/cspractice/cs_install.php — use localhost as host, root as username, root as password (MAMP default)
6. Delete cs_install.php after installation

MAMP is ideal for testing and development. For a permanent practice server, use the Homebrew/Caddy setup above — it runs as a proper background service and starts automatically on boot.

Condition value list

The primary condition dropdown covers the most common presenting complaints seen in musculoskeletal and naturopathic practice:

Head · Neck · Shoulder · Thoracic Ribs · Low Back · Knee · Stress · Naturopathic · General · O-A · Hip · Bowels · IHD · DVT · >BP · CD Junction · Skin · Anxious · Diabetes · Tiredness · Migraine · Baby Can't Sleep - Colic · Lupus · Peripheral Vascular Disease · Dizziness · Ankle/Feet · ME · PID · Reduced Sight · Thyroid · Coccyx · TMJ · Sinus · Elbow · Wrist/Hand · Bell's Palsy · Gen Cranial

Custom conditions not in this list can be noted in the yellow notes field or session treatment notes.

Structural orthopaedic tests

Red flag conditions

The following should prompt consideration of urgent referral and use of the red flag field on the patient record:

• +VE percussion suggesting fracture
• Aortic pulse prominence (possible aneurysm)
• Unexplained weight loss with back pain
• Bilateral neurological symptoms
• Saddle anaesthesia (cauda equina)
• Copper wiring or signs of hypertensive retinopathy
• Ca (cancer) smell
• Jaundice / hepatomegaly
• Pear drops breath (diabetic ketoacidosis)

Treatment value list

Structural · Cranial · Nutritional · Herbal · Homeopathic · Visceral · Acupuncture · GOT · AK · Meridian · Mobilise