# System Administrator Guide

## Overview

The **System Admin** role (`system_admin`) is separate from the church **Admin** role (`admin`).

**What system admins can do**

- Use the **System console** at `/system`: health, security overview, activity logs, global settings, database table overview, file logs, backups.
- **Manage user accounts** from **System → System Users** (`/system/users`): list all logins, create **system** admins and **church-role** users (**admin** plus the same staff roles as **Users** in the main app: clerk, data collector, finance, voting, group manager), edit those users (including **changing role** among church admin + staff and **generational groups** for group managers), and **delete** church-role users (not other system admins). **Group managers** can be assigned generational groups here (same as `/users`).
- See **security-related** information tied to logins (e.g. failed attempts by IP, recent successful logins with user names) on **Security** and **Activity**.

**What system admins cannot do**

- Open **church application modules**: members, finance, events, voting UI, mobile field app, etc. The app redirects them to `/system` if they try (`index.php` routing).

So: they do **not** browse or edit **member records, offerings, events content**, etc. They **do** handle **accounts, infrastructure, and settings** that affect the whole installation.

## Roles comparison (summary)

| Role | Typical use |
|------|-------------|
| **system_admin** | `/system` only: maintenance, backups, settings, **user account** lifecycle for all roles, security views |
| **admin** | Full church data in the main app; **Users** page lists church roles (not `system_admin`) |
| **clerk**, **finance**, **voting**, **group_manager**, **data_collector** | Scoped areas per permissions |

Church **admin** and **system_admin** can both affect **users**, but through different screens: **`/users`** vs **`/system/users`**. Only **system_admin** can create or list other **system_admin** accounts.

## Creating a System Admin User

### Method 1: Via Database

Use PHP `password_hash`, not MySQL `PASSWORD()`.

### Method 2: Via temporary PHP script

See historical examples in git or use `install/create-system-admin.php` pattern: insert into `users` with `role = 'system_admin'`.

### Method 3: Via install script

`install/install.php` creates a default system admin:

- Username: `sysadmin`
- Password: `sysadmin123`
- **Change this password immediately after installation.**

### Method 4: Via System console (recommended after install)

Log in as a system admin → **System Users** → **Create System Admin**.

## System Admin Interface (`/system`)

1. **Dashboard** — PHP/MySQL info, disk, database summary stats, log file list, recent activity counts, **file upload storage** (`public/uploads`), and **latest SQL backup age** (warns if older than 7 / 30 days).
2. **System Health** — Memory, disk, MySQL status, PHP limits, **upload folder size**, **backup freshness**, and notes on **HTTPS** + **session cookies** (Secure / SameSite / browser session behaviour). On **tablets and narrow windows** (about 1024px and below), use the **menu (☰)** control to open the sidebar; tap outside the menu or press **Escape** to close.
3. **Security** — Failed logins, blocked IPs, recent successful logins.
4. **Activity Logs** — Audited actions where implemented.
5. **Settings** — Site name, base path, timezone, SMTP/SMS, security (session timeout, IP lists), etc.
6. **Database** — Table list, sizes; dangerous clean-data tools (use with extreme care).
7. **Logs** — Application log files.
8. **Backup** — SQL backups under `backups/`; the page shows a **freshness notice** if there are no files or the newest `.sql` is stale.
9. **System Users** — All accounts: system admins (read-only list) and church users (create / edit / delete per rules above).

## Access control (enforced in code)

- **system_admin** may only use **`/system`**, **`/login`**, **`/logout`** (and password change if applicable). Any other route redirects to `/system`.
- **Church roles** cannot open **`/system/*`**; they are redirected to their home area.

## Security notes

1. **Destructive actions** (truncate/clean database tables, delete SQL backups, delete users from System Users) require a **CSRF token** on the form and your **account password** (or exact phrase for clean-data). There is **no in-app database restore**; restores are done via MySQL/phpMyAdmin so a stolen session alone cannot wipe backups through a “restore” button.
2. Use **dedicated** credentials for `system_admin`; do not share with church admin day-to-day accounts.
3. **Deleting users** from System Users removes **login access**; coordinate with church leadership before removing church admins or clerks.
4. **System admins see usernames and names** in user lists and some security views — not member pastoral notes, but still treat the role as **highly privileged**.
5. Change default **`sysadmin`** password immediately on any new install.

## Default credentials (install script)

After `install/install.php` (change both immediately):

| Account | Username | Password |
|---------|----------|----------|
| Church admin | `admin` | `admin123` |
| System admin | `sysadmin` | `sysadmin123` |

**Do not commit real passwords to the repo;** use `PASSWORDS.md` or a secrets store only on secure machines.