Admin Guide

This guide documents administrative procedures for church administrators and Super Admins operating Flockbase.

Admin Account Operations

Creating an Admin

Only Super Admins have permission to provision administrative accounts.

POST /admin/admin-accounts
Authorization: Bearer <super_admin_jwt>
Content-Type: application/json

{
  "name": "Pastor Deborah Adeleke",
  "email": "deborah@church.org",
  "phone": "+2348012345678",
  "password": "TemporaryPassword123!"
}

Automated Workflow:

1. The backend asserts that the email address is not already registered.
2. The password is cryptographically hashed with bcrypt (12 salt rounds).
3. The user record is created with role: ADMIN and status: ACTIVE.
4. A welcome email is dispatched to the recipient containing:
   • Their temporary credentials.
   • Login link to https://flockbase.live/login.
   • Instructions to change password upon first login.
5. If the email fails to deliver (e.g. invalid domain), the user creation is preserved, and a warning is logged to the server telemetry without aborting the request.

Promoting an Admin to Super Admin

Super Admins can elevate existing ADMIN users to SUPER_ADMIN.

• Endpoint: POST /admin/admin-accounts/:id/promote
• Constraint: Strict maximum of 5 active Super Admins.
• Audit: Every promotion is logged with the acting Super Admin's ID and timestamp.

Deactivating an Admin

Super Admins can deactivate an administrator account at any time:

• Endpoint: PATCH /admin/admin-accounts/:id/deactivate
• Deactivation invalidates all current refresh tokens, terminating existing sessions immediately.

Unit Management & Department Governance

Administrators manage church departments and workforce ministries under Units:

Unit Lifecycle

1. Creation (POST /units):
   • Provide unit name and optional description.
2. Assigning Leadership (PATCH /units/:id/leader):
   • Assign an active worker as UNIT_LEADER or ASSISTANT_UNIT_LEADER.
   • The user's role is automatically updated in the database to match their leadership designation.
3. Unit Deletion / Archival:
   • Units with active workers cannot be deleted until all members are reassigned or archived.

Worker Lifecycle & Directory

Administrators have global visibility across all church workers:

Worker Filtering & Search

• Endpoint: GET /workers
• Supported Query Parameters:
  • unitId: Narrow results to a specific unit.
  • role: Filter by WORKER, UNIT_LEADER, or ASSISTANT_UNIT_LEADER.
  • status: Filter by ACTIVE or INACTIVE.
  • page & pageSize: Defaults to page 1, 50 workers per page.

Blocking Accounts

When an account is compromised or subject to formal church disciplinary action, administrators can execute a governance block:

• Endpoint: POST /governance/blocked-accounts/:id/block
• Requires a mandatory reason string (e.g., "Suspected credential compromise").
• The user's status changes to BLOCKED, and all issued refresh tokens are instantly revoked.

Audit Logs & Compliance

Flockbase maintains an immutable ledger of administrative events.

Monitored Events

• Admin account creation & promotion
• Account deactivation & block operations
• Unit leader assignments and replacements
• Member reassignment across units
• Attendance status adjustments and excuse approvals

Querying Audit Logs

• Endpoint: GET /governance/audit-logs
• Query by actorId, targetType (e.g., User, Unit), or date range.