# Chapter 1 — Introduction

## 1.1 What is Acacia CMS?

Acacia CMS (Church CMS) is a cloud-based church management platform. It helps you manage:

- **People** — members, groups, departments, follow-ups
- **Attendance** — manual entry, kiosk QR check-in, reports
- **Finance** — offerings, tithes, pledges, expenses, reports
- **Events** — services, calendar events, announcements, messages
- **Staff** — employees, payroll, user accounts, roles
- **Organization** — branches, designations, localization (multi-site churches)

Everything runs in your web browser. No software installation is required on your computer.

---

## 1.2 Who uses the system?

| Role | Description | What you see |
|------|-------------|--------------|
| **Founding church admin** | The account created when your church registered. No role assigned. | Full church menu — everything your plan includes |
| **Founding branch admin** | Admin of one branch in a multi-site church | Full branch menu — scoped to your location |
| **Staff with a role** | Users created by your admin (Treasurer, Secretary, etc.) | Limited sidebar — only permitted modules |
| **Members (public)** | No login required | Kiosk check-in page only |

**Founding admin** = first user, full access (within plan limits).

**Role-based staff** = permissions set in **Administration → Roles → Permissions**.

---

## 1.3 Single church vs multi-branch headquarters

### Single congregation

One church, one location. You see:

- Members, Attendance, Finance, Events, HRM, Administration
- No **Branches** menu

### Multi-branch headquarters (HQ)

A head office managing multiple locations:

| HQ manages | Branches manage |
|------------|-----------------|
| Branches (create, edit, deactivate) | Members and attendance |
| Designations (org-wide titles) | Day-to-day finance |
| Localization (regions, districts, areas, zones) | Services and events |
| Consolidated finance reports | Branch users and roles |
| HQ announcements (pushed to branches) | Common fund contributions |

---

## 1.4 Plans, limits, and features

Your subscription **plan** controls two things:

### Feature access

If a module is missing from your sidebar, either:

1. Your plan does not include it, **or**
2. Your role does not grant **Read** permission

Contact your administrator or upgrade your plan.

**Note:** Plan features are configured as a single list — when a module is included in your plan, it works for single churches and branches alike. You no longer need separate “branch vs church” ticks for the same feature.

### Numeric limits

| Limit | Meaning |
|-------|---------|
| Empty / blank | Unlimited |
| `0` | Not allowed |
| Positive number | Maximum count |

Applies to **branches**, **members**, and **users**.

View your current plan: **Platform Billing → Plan package**.

---

## 1.5 Permissions explained

Each module supports six actions:

| Action | What it allows |
|--------|----------------|
| **Read** | View lists and details |
| **Write** | Edit existing records |
| **Create** | Add new records |
| **Delete** | Remove records |
| **Import** | Bulk import (where available) |
| **Export** | Download CSV/Excel/PDF |

Buttons only appear when your role grants the action. Sidebar links require **Read**.

---

## 1.6 Signing in

### Step 1 — Open your church website

Go to your church's public URL (e.g. `https://yourchurch.com`).

![Sign in screen](../assets/screenshots/01-sign-in.png)
*Figure 1.1 — Landing page sign-in form*

### Step 2 — Enter credentials

1. Click the **Sign in** tab (if not already active).
2. Enter your **email address**.
3. Enter your **password**.
4. Click **Sign in**.

### Step 3 — Where you land

| Account type | Destination |
|--------------|-------------|
| Church founding admin | Church dashboard |
| Branch founding admin | Branch dashboard |
| Staff with a role | User dashboard |
| Suspended church | Suspension message — contact platform support |

### Forgot password

Use **Forgot password** on the login page (requires email/SMTP to be configured).

### Two-factor authentication

If enabled, you will be asked for an authenticator code or email OTP after password entry.

---

## 1.7 First-time tutorial modal

When you sign in for the first time, a **welcome tutorial** walks you through available modules.

| Option | Effect |
|--------|--------|
| **Next** | Continue through tutorial steps |
| **Skip** | Hide for this browser session |
| **Don't show again** | Never show again (saved to your account) |

The tutorial adapts to your role and plan — it only shows modules you can access.

---

## 1.8 Glossary

| Term | Definition |
|------|------------|
| **Tenant** | Your church organization in the system |
| **HQ / Head office** | Main church account managing multiple branches |
| **Branch** | A location/site under a multi-branch church |
| **Founding admin** | First user without a role; full tenant access |
| **Role** | Named permission set (e.g. Treasurer) |
| **Plan** | Subscription package with features and limits |
| **Kiosk** | Public check-in page (no login) |
| **Gift Aid** | UK tax reclaim on donations |
| **Visitor form** | Customisable template for registering first-time guests |
| **Designation type** | Category for an org-wide title (Pastor, Elder, etc.) |
| **Common fund** | Shared financial pool across branches |

---

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Module missing from sidebar | Check plan features and role permissions |
| Cannot add member/branch/user | Plan limit reached — upgrade or contact admin |
| Wrong dashboard (church vs branch) | Admin must correct your branch assignment |
| Login blocked after many attempts | Wait one minute (rate limiting) then retry |
| 419 error on login | Clear browser cookies; ensure HTTPS in production |

---

[Next: Chapter 2 — Navigation →](02-navigation.md)
