Feature: Dedicated Church Information Configuration (First-Run UX)

[DawoudIO]

Feature: Dedicated Church Information Configuration Page (First-Run UX)

Problem Statement

Currently, when a new ChurchCRM installation is completed, church-level information (name, address, logo, etc.) is mixed into the generic Edit General Settings page alongside technical system configuration. This creates a confusing first-run experience for administrators.

Solution

Create a dedicated admin-only page at /admin/church-info that:

• Organizes church metadata using a tabbed interface
• Separates church info from system/technical settings
• Enforces critical field completion during first run
• Improves user experience with clear, focused forms

Implementation Overview

Page Structure: /admin/church-info

Tabs:

1. Basic Information (name, website, logo)
2. Location (address, city, state, zip, country)
3. Contact (phone, email)
4. Map & Coordinates (latitude, longitude, timezone)
5. Display Options (custom header, letterhead)

Architecture

• Routes: Add to /admin/routes/system.php
• Controller: New ChurchInfoController for GET/POST/AJAX
• View: src/admin/views/church-info.php with Bootstrap tabs
• Middleware: New ChurchInfoRequiredMiddleware for first-run enforcement
• Database: Uses existing system_config entries (no schema changes)

First-Run Enforcement

• Middleware checks if sChurchName is empty
• Redirects non-exempt routes to /admin/church-info
• Dashboard displays warning if incomplete
• Exempt routes: /admin/church-info, /logout, API auth endpoints

Configuration Fields

All existing SystemConfig entries (no new fields):

• sChurchName, sChurchAddress, sChurchCity, sChurchState
• sChurchZip, sChurchCountry, sChurchPhone, sChurchEmail
• iChurchLatitude, iChurchLongitude, sTimeZone
• sChurchWebSite, custom header, letterhead paths

Documentation

• Update docs.churchcrm.io first-run guide with screenshots
• Add new "Church Info" page to docs
• Update wiki if applicable

Testing Requirements

• Auth: Only admins can access
• Form save (POST + AJAX)
• Validation: Church name required
• Middleware: No redirect loops, proper exemptions
• Dashboard: Status reflects saved state
• Finance dashboard: Existing checks still work

Success Criteria

✅ Page displays organized church config tabs
✅ Form saves successfully (both POST and AJAX)
✅ First-run redirect enforces completion
✅ Dashboard warnings display correctly
✅ Documentation updated
✅ Tests pass
✅ Backward compatible with existing SystemSettings

Timeline

• Dev (routes/controller/view/middleware): 2-3 days
• Testing (unit + Cypress): 1 day
• Docs: 1 day
• Review & refinement: 1-2 days

Total: 5-7 development days

[github-actions]

Thanks for opening an issue!

We couldn't auto-detect the issue type. To help us route your issue correctly, please do one of the following:

1. Add a label: Add the Type:Bug or Type:Question label to this issue (if you have permission)
2. Re-create with a template: Close this issue and create a new one using the Bug Report or Question template
3. Just tell us: Reply below with whether this is a bug report or a question, and provide the relevant details

---

For bug reports, please include:

• A short summary of the problem
• Steps to reproduce (if you have them)
• Any relevant logs or screenshots (redact private data)

For questions, please include:

• What you're trying to do
• What you've already tried

To collect system debug info, if you're an admin:

👉 Admin → System Maintenance → System Logs (or click the debug icon)

Advanced users: If the issue is reproducible in the UI, the Cypress Recorder helps. Capture the steps and attach an exported spec.

👉 Bug Reporting & Diagnostics Guide

---

Note: ChurchCRM is maintained by volunteers. While we try to respond to every issue quickly, there may be a delay in our response depending on availability. Thank you for your patience! 🙏

[DawoudIO]

Planning Complete ✅

I've created comprehensive documentation for this feature:

QUICKSTART-CHURCH-INFO.md - Developer guide with step-by-step walkthrough and code examples
IMPLEMENTATION-CHURCH-INFO.md - Detailed technical spec with architecture and testing strategy
CHURCH-INFO-WIREFRAMES.md - UX wireframes, UI specs, and accessibility requirements

All reference materials are in the repo root. Ready for implementation! 🚀