DOCSEARCHbyAlgolia
Submit Docs

ChurchCRM Documentation

repository·master·Indexed 21 days ago

https://github.com/churchcrm/crm

Open-source church management system providing professional tools for congregations. Documentation covers version 7.6.0, including Docker deployment options (Nginx, PHP-FPM, and FrankenPHP), development and testing profiles, Cypress end-to-end test execution, and OpenAPI specification generation for public and private APIs.

Tokens
33K
Snippets
59
Records
203
Agent score
75%

What's inside ChurchCRM

  1. Configure Maps with Leaflet.js

    master

    ChurchCRM has migrated from Google Maps and Bing Maps to Leaflet.js. This change provides a free, private-by-default mapping experience.

    Benefits and Changes

    • No API Keys: No Google Maps API key is required; maps work with zero configuration.
    • Privacy: Family data is no longer sent to Google for rendering.
    • Directions: Every family and person view includes a Get Directions button that deep-links to the user's preferred mapping app (Google Maps, Apple Maps, Waze, etc.).
    • Removed: Bing Maps is no longer supported.

  2. Understand the Knowledge Vault structure and purpose

    master

    The Knowledge Vault is a specialized view of the repository's development context. It is intended for human navigation using Obsidian's graph view and backlinks, rather than for machine consumption.

    Key Components

    • skills/: A symlink to .agents/skills/. This contains the actual skill files used by Claude Code. For a task-based index, start at skills/churchcrm/SKILL.md.
    • CLAUDE.md: A symlink to the repository's main CLAUDE.md file.

    Important Distinctions

    • Human vs. Machine: The vault is for human browsing. It does not change how Claude Code loads context. Claude Code continues to use the task-based lookup tables in CLAUDE.md and skills/churchcrm/SKILL.md to maintain token efficiency by only reading relevant skills.

  3. Seed event attendance using `attended_fraction`

    master

    To create realistic mixed attendance for past events, use the attended_fraction column (a value between 0.0 and 1.0) in your events.csv. This is processed by DemoDataService::seedEventAttendance().

    How it works:

    1. The system loads members of the groups linked via link_groups (using person2group2role_p2g2r).
    2. It calculates the number of attendees as ceil(fraction × memberCount).
    3. The first N members (ordered by person ID) receive an event_attend row with the checkin_date set to the event end time.
    4. Members not included in this count receive no event_attend row, which allows them to appear as "Did Not Attend" in card queries where event_attend.event_id IS NULL.

    Note: attended_fraction only applies to past events (event_end < now). For future events or if the fraction is 0, no attendance rows are created.

  4. How term extraction works

    master

    The npm run locale:build command aggregates terms from four distinct sources into a single locale/messages.po file (typically containing 2,292+ terms):

    1. Database Terms: Queries user-defined terms and system data via MySQL.
    2. Static Data: Extracts country names and locale display names from the PHP Countries class library.
    3. PHP Source Code: Scans PHP files for gettext(), _(), and ngettext() calls using xgettext (excluding vendor/).
    4. JavaScript/React: Scans .tsx and .js files for t() and i18next.t() calls using i18next-parser.

  5. How the ChurchCRM plugin architecture works

    master

    ChurchCRM uses a WordPress-style plugin architecture to extend functionality without modifying core code. There are two types of plugins:

    1. Core plugins (src/plugins/core/): Maintained within the main repository and shipped with ChurchCRM.
    2. Community plugins (src/plugins/community/): Third-party extensions installed at runtime via an admin-only URL installer. These are gated by an approved-plugins allowlist (src/plugins/approved-plugins.json) to ensure security.

    Community plugins are excluded from orphan-scan and signature generation processes to allow for dynamic runtime installation.

  6. Use the 'Cart to Group' utility for group management

    master
    You can move individuals from your active cart directly into a permanent church group or volunteer team. This utility functions similarly to the 'Cart to Event' feature, allowing you to push an accumulated list of people from your cart into any existing group with a single click.

  7. Security: Content-Security-Policy (CSP) and Inline Scripts

    master

    Starting with version 7.1.1, ChurchCRM has implemented stricter Content-Security-Policy (CSP) enforcement. To ensure scripts execute correctly under these policies, the following changes were made:

    • Nonce implementation: Inline <script> tags (such as those in the admin export page) now include nonce attributes.
    • Event Handlers: Inline onclick handlers have been removed from custom field editors (Group, Family, and Person). These have been replaced with data-* attributes and delegated event listeners to comply with CSP requirements.

  8. View Birthday and Anniversary lookaheads on the Dashboard

    master
    The Dashboard provides a 14-day lookahead for birthdays and anniversaries. Instead of only showing events occurring today, the dashboard now displays upcoming events for the next two weeks to assist administrators with outreach. The view uses horizontal tabs for navigation.

  9. Compare Dev vs Test Docker profiles

    master

    Choosing between the Dev and Test profiles depends on your host environment and goals.

    FeatureDev Profile
    Host requiresDocker only
    Code locationBind-mounted (edit locally)
    Build runsInside container
    Best forLive development, no host tools
    Image includesFull dev toolchain (Node, Composer)
    Code changesInstant reload
    FeatureTest Profile
    Host requiresDocker + Node + PHP + Composer
    Code locationBind-mounted (edit locally)
    Build runsOn host (npm run build)
    Best forCI-like, verify compiled app
    Image includesMinimal runtime only
    Code changesEdit $\rightarrow$ npm run build $\rightarrow$ restart

  10. Kiosk Smart-Refresh behavior

    master
    The Kiosk check-in system uses a 60-second smart-refresh cycle. This is designed to reduce network load and Wi-Fi congestion compared to previous high-frequency refresh cycles, while maintaining up-to-date check-in data.

  11. Use the ChurchCRM Hooks system

    master

    ChurchCRM uses a WordPress-style hook system via HookManager::addAction and HookManager::addFilter. Hooks are categorized by the data they touch. If a hook accesses PII or financial data, you must declare the corresponding capability tag (e.g., hooks.person) in your approved registry entry.

    Hook Categories:

    • People / Family: PERSON_*, FAMILY_*, *_VIEW_TABS
    • Financial: DONATION_RECEIVED, DEPOSIT_CLOSED
    • Events / Groups: EVENT_*, GROUP_MEMBER_*
    • Email / SMS: EMAIL_PRE_SEND, EMAIL_SENT
    • UI: MENU_BUILDING, DASHBOARD_WIDGETS, SETTINGS_PANELS, ADMIN_PAGE
    • System: SYSTEM_INIT, SYSTEM_UPGRADED, CRON_RUN, API_RESPONSE

  12. Understand the redesigned Notification system

    master

    In version 7.1.1, the notification system was redesigned to improve performance and security. Instead of the previous method of polling the API on every page load (GET /api/system/notification), ChurchCRM now uses a session-backed notification registry.

    Key changes for developers:

    • Fetching: Remote notifications are now fetched once during the login process using NotificationService::fetchRemoteNotifications().
    • Rendering: Notifications are rendered server-side within Header.php.
    • Deprecation: Legacy API endpoints used for polling notifications have been removed.