[PLAN] Location-Based Multi-Campus System for Proclaim 10.1

[bcordis]

[PLAN] Location-Based Multi-Campus System for Proclaim 10.1

📋 Overview

This Discussion presents the complete implementation plan for location-based multi-campus access control in Proclaim 10.1. This is a comprehensive enhancement that replaces access-level-based campus separation with a flexible location-based system.

Estimated Effort: 92 hours (~11.5 developer days)
Target Release: Proclaim 10.1
Breaking Changes: None (opt-in feature)

🎯 Goals

Replace access-level-based campus separation with a flexible system supporting:

• ✅ Group-based campus restrictions (Campus A Managers → Campus A only)
• ✅ Teacher-based auto-access (teachers see their content everywhere)
• ✅ Optional restrictions (unrestricted locations visible to all)
• ✅ Hybrid security (locations + access levels for multisite sync)
• ✅ Guided setup wizard (opt-in, simple mode aware)
• ✅ Production-ready UX (inline help, safety checks, comprehensive docs)

🏗️ Architecture

Three-Source Access Model

User's Visible Locations =
    1. Group Locations        (via user group → location mapping)
  + 2. Teacher Locations      (where user has taught)
  + 3. Unrestricted Locations (no group mapping configured)

Super admins: Bypass all filters (see everything)

Hybrid Security (Locations + Access Levels)

public static function applySecurityFilter($query, string $alias = 'study'): void
{
    // Primary: Location-based campus separation
    CwmlocationHelper::applyLocationFilter($query, $alias);

    // Secondary: Access level filtering (for multisite sync)
    $user = Factory::getApplication()->getIdentity();
    if (!$user->authorise('core.admin')) {
        $db = Factory::getContainer()->get(DatabaseInterface::class);
        $query->whereIn(
            $db->quoteName($alias . '.access'),
            $user->getAuthorisedViewLevels()
        );
    }
}

Joomla ACL Integration

Uses standard Joomla permissions only (no custom ACL actions):

Permission	Usage
core.admin	Bypass all location filtering
core.manage	Access component configuration
core.edit	Edit messages in accessible locations
core.edit.own	Edit own messages regardless of location

Location Filtering = Admin organizational tool (not a permission)
Teacher Auto-Access = Extends core.edit to messages where user is listed as teacher

📊 Implementation Phases

Phase	Description	Hours
1	Core Infrastructure	16
2	List Models & Statistics	8
3	Edit Permissions	3
4	Migration Logic	6
5	Location Management Safety	8
6	Setup Wizard	15
7	Batch Operations & CSV Import	8
8	Edit Form UX & Empty States	9
9	Server Location Support	4
10	Module Location Filtering	5
11	Search & Finder Integration	2
12	Documentation	6
Total		92

🎨 User Experience

Edit Form Mental Model

Simple, intuitive location field:

Campus / Location: [(Empty - Unrestricted) ▼]
  ℹ️ Only users with access to this location will see
     this message. Leave empty for unrestricted (visible
     to all).

Access Level: [Public ▼]
  ℹ️ Controls who can view on the frontend. Location
     controls backend admin lists.

Key UX Principles:

• ✅ Default to permissive (empty = unrestricted)
• ✅ Show only relevant options (dropdown filtered to user's locations)
• ✅ Explain in context (inline help at point of decision)
• ✅ Distinguish backend vs frontend (location ≠ access level)

Zero-Location Empty State

When a user has no accessible locations:

📍 No Locations Assigned

You don't have access to any locations yet.

You need to be either:
• A member of a group assigned to a campus (e.g., Campus A Managers)
• A teacher with messages in the system

Contact your administrator to request location access.

🔧 Technical Details

New Files (8)

• admin/src/Helper/CwmlocationHelper.php - Core logic (450 lines)
• admin/src/Field/AccessibleLocationsField.php - Dropdown (150 lines)
• admin/src/Field/LocationGroupMappingField.php - Subform (200 lines)
• admin/src/Model/CwmlocationwizardModel.php - Wizard backend (450 lines)
• admin/src/Controller/CwmlocationwizardController.php - AJAX (200 lines)
• admin/src/View/Cwmlocationwizard/HtmlView.php - Wizard view (100 lines)
• admin/tmpl/cwmlocationwizard/default.php - Wizard UI (600 lines)
• build/media_source/js/location-wizard.es6.js - JS (400 lines)

Updated Files (21)

• Component configuration (location management tab)
• 5 edit forms (message, series, podcast, server, location)
• 7 models (messages, locations, location, message, servers, csvimport, install)
• Statistics library (7 methods)
• Migration helper
• 3 templates (messages list, cpanel, batch)
• CSV import JS
• Module configuration & helper
• Finder plugin

Database Changes

• Composite indexes for performance (6 tables)
• Server location_id column

Language Keys

• ~80 new keys (inline help, tooltips, wizard, errors)

Documentation

• Admin setup guide (wiki)
• User guide (wiki)
• Developer API reference (wiki)

🛡️ Safety & Quality

Safety Checks:

• Location deletion blocked when in use
• Batch operations restricted to accessible locations
• CSV import validates location access
• Enable/disable toggle for rollback

Performance:

• Composite indexes for location filtering
• No N+1 queries introduced
• All queries use existing indexes

Testing:

• Unit tests for CwmlocationHelper
• Integration tests for all 12 phases
• Migration tests (9.2.8 → 10.1)
• Edge case handling

📖 Use Cases

Example 1: Multi-Campus Church

NFSDA has:

• Main Campus (restricted to Main Campus Managers)
• Downtown Campus (restricted to Downtown Campus Managers)
• Conference Center (unrestricted - visible to all)
• Youth Retreat Location (unrestricted)

Setup:

1. Create 2 groups: Main Campus Managers, Downtown Campus Managers
2. Map locations to groups in component config
3. Leave Conference Center & Youth Retreat unmapped
4. Link teachers to user accounts

Result:

• Campus managers see only their campus
• Teachers see everywhere they've taught
• Conference recordings visible to all staff
• Frontend uses access levels (unchanged)

Example 2: Teacher Cross-Campus Access

Pastor John teaches at:

• Main Campus (50 messages)
• Downtown Campus (20 messages)
• Conference Center (5 messages)

Without location system: Needs to be in multiple groups
With location system: Link teacher record to user account → automatic access to all 75 messages

Example 3: CSV Bulk Import

title,teacher,series,location
"Sunday Sermon",Pastor John,Gospel of John,Main Campus
"Conference Talk",Guest Speaker,Annual Conference,
"Youth Message",Pastor Sarah,Youth Series,Downtown Campus

Empty location = unrestricted. Import validates user has access to assigned locations.

🚀 Migration from 9.2.8

Auto-detection identifies one of 3 scenarios:

Scenario 2A: Access-based separation

• Multiple access levels detected
• Auto-creates locations from access level names
• Maps messages: access level → location
• Creates group mappings
• Normalizes access to Public

Scenario 2B: Already using locations

• No data migration needed
• Just add group mapping UI

Scenario 2C: Single campus

• Creates default "Main Campus" location
• Assigns all messages to it

Rollback: Wizard creates backup before applying. Restore via backup or disable feature toggle.

📅 Rollout Plan

Development: feature-location-system branch
Beta: Opt-in testing in 10.1-beta
Stable: Full release in 10.1
Documentation: 3 wiki guides + inline help

💬 Questions for Community

1. UX Feedback: Is the "Location vs Access Level" distinction clear enough in the inline help?
2. Wizard Flow: 7-step wizard - too many steps or appropriate for complexity?
3. Default Behavior: Should new messages default to empty (unrestricted) or first accessible location?
4. Teacher Linking: Auto-create user accounts for unlinked teachers during wizard, or skip?
5. Frontend Filtering: Keep frontend using access levels only, or add optional location dropdown for visitors?

📎 Related Links

• Full Master Plan: /tmp/location-system-master-plan-v2.md
• Comprehensive Review: /tmp/location-plan-comprehensive-review.md
• Epic Issue: #TBD
• Project Board: TBD

🤝 How to Contribute

Feedback Welcome On:

• UX clarity and simplicity
• Missing edge cases
• Performance concerns
• Documentation gaps
• Alternative approaches

Testing Volunteers Needed For:

• Multi-campus installations
• Migration from 9.2.8
• Wizard usability
• Non-English translations

---

Status: Planning phase complete, ready for community review before implementation begins.

Next Steps: Create phase issues, get community feedback, begin Phase 1 implementation.

[bcordis]

Implementation Status

The multi-campus location system shipped in v10.1.0 with 7 of 9 phases complete. The system is fully functional for multi-campus access control.

Completed (v10.1.0)

• Phase 1: Core Infrastructure (CwmlocationHelper with full filtering)
• Phase 2: List Models (8 admin models have location filtering)
• Phase 4: Migration Logic (8 SQL migration files)
• Phase 6: Setup Wizard (full wizard with scenario detection)
• Phase 7: CSV Import (location column support)
• Phase 8: Edit Form UX (location dropdowns on messages, servers)
• Phase 9: Server Location Support (location_id on servers)

Remaining Work — tracked as issues

• Teacher auto-access: link teachers to Joomla user accounts #1180 — Teacher auto-access: link teachers to Joomla user accounts (Phase 3)
• Location delete safety: merge/reassign entities before deletion #1181 — Location delete safety: merge/reassign entities before deletion (Phase 5)

This discussion can be closed once #1180 and #1181 are resolved.