CPR DevDocs

Appearance

Branch Management View - User Guide ​

Overview ​

The Branch Management interface provides a comprehensive web-based UI for managing clinic branches in your multi-branch CPR system.

Accessing Branch Management ​

URL: /admin/branches

Requirements:

  • User must be authenticated
  • User must have verified email
  • Recommended: Admin role for access control

Features ​

1. View All Branches ​

The main view displays all branches in a grid layout with:

  • Branch name and code
  • Active/Inactive status badge
  • Address and contact information
  • Number of assigned staff members
  • Action menu for each branch

2. Search Functionality ​

Search branches by:

  • Branch name
  • Branch code
  • Address

3. Create New Branch ​

Click the "Add Branch" button to open the create dialog.

Required Fields:

  • Branch Name
  • Branch Code (must be unique)
  • Address

Optional Fields:

  • Phone number
  • Email address
  • Active status (default: active)

Example:

Name: Main Clinic
Code: MAIN
Address: 123 Healthcare Avenue, City 12345
Phone: +1234567890
Email: main@clinic.com
Active: ✓

4. Edit Branch ​

Click the menu button (⋮) on any branch card and select "Edit" to:

  • Update branch information
  • Change contact details
  • Modify address
  • Update branch code

5. Toggle Branch Status ​

Click the menu button (⋮) and select:

  • "Deactivate" - to mark branch as inactive
  • "Activate" - to mark branch as active

Note: Inactive branches are still visible but marked with a red "Inactive" badge.

6. Delete Branch ​

Click the menu button (⋮) and select "Delete" to remove a branch.

Important:

  • Branches with assigned users cannot be deleted
  • You must reassign all users before deletion
  • This action cannot be undone

UI Components ​

Branch Card ​

Each branch is displayed in a card showing:

┌─────────────────────────────────────┐
│ Main Clinic              [Active] ⋮ │
│ MAIN                                │
│                                     │
│ 123 Healthcare Avenue               │
│ 📞 +1234567890                      │
│ ✉️ main@clinic.com                 │
│ 👥 15 staff members                 │
└─────────────────────────────────────┘

Status Badges ​

  • Active (Green badge): Branch is operational
  • Inactive (Red badge): Branch is not currently active

Flash Messages ​

Success and error messages appear at the top of the page:

  • ✅ Green background: Success messages
  • ❌ Red background: Error messages

Workflow Examples ​

Creating a New Branch ​

  1. Click "Add Branch" button
  2. Fill in the form:
    Branch Name: Downtown Branch
Branch Code: DWTN
Address: 456 Central Street, Downtown
Phone: +1234567891
Email: downtown@clinic.com
Active: ✓
  3. Click "Create Branch"
  4. Success message appears
  5. New branch appears in the grid

Editing a Branch ​

  1. Locate the branch in the grid
  2. Click the menu button (⋮)
  3. Select "Edit"
  4. Update the information
  5. Click "Update Branch"
  6. Changes are saved and reflected immediately

Deactivating a Branch ​

  1. Find the branch card
  2. Click the menu button (⋮)
  3. Select "Deactivate"
  4. Branch status changes to "Inactive"
  5. Red badge appears on the card

Deleting a Branch ​

  1. Ensure branch has no assigned users
  2. Click the menu button (⋮)
  3. Select "Delete"
  4. Confirm deletion in the dialog
  5. Branch is removed from the system

Validation Rules ​

Branch Name ​

  • Required
  • Maximum 255 characters
  • Can contain any characters

Branch Code ​

  • Required
  • Maximum 50 characters
  • Must be unique across all branches
  • Usually uppercase (e.g., MAIN, DWTN, NORTH)

Address ​

  • Required
  • No maximum length
  • Full physical address recommended

Phone ​

  • Optional
  • Maximum 20 characters
  • Format: +1234567890 (recommended)

Email ​

  • Optional
  • Must be valid email format
  • Maximum 255 characters

API Endpoints (Backend) ​

The view interacts with these Laravel routes:

php
GET    /admin/branches           - List all branches
POST   /admin/branches           - Create new branch
PUT    /admin/branches/{id}      - Update branch
DELETE /admin/branches/{id}      - Delete branch
PATCH  /admin/branches/{id}/toggle - Toggle active status

Security & Permissions ​

Current Implementation ​

  • Requires authentication (auth middleware)
  • Requires verified email (verified middleware)

Add role-based access control:

php
Route::middleware(['auth', 'verified', 'role:admin'])->group(function () {
    // Branch management routes
});

Technical Details ​

Frontend Stack ​

  • Framework: Vue 3 with TypeScript
  • UI Components: Shadcn/ui components
  • State Management: Inertia.js
  • Styling: Tailwind CSS

Backend Stack ​

  • Framework: Laravel 12
  • View Engine: Inertia.js
  • Validation: Laravel Form Requests
  • Database: Eloquent ORM

File Locations ​

Frontend:

  • View: resources/js/pages/admin/Branches.vue

Backend:

  • Controller: app/Http/Controllers/Admin/BranchController.php
  • Model: app/Models/Branch.php
  • Routes: routes/web.php (admin.branches.* routes)

Customization ​

Adding More Fields ​

To add custom fields to branches:

  1. Create Migration:
bash
php artisan make:migration add_custom_fields_to_branches_table
  1. Update Model (app/Models/Branch.php):
php
protected $fillable = [
    'name',
    'code',
    'address',
    'phone',
    'email',
    'is_active',
    'settings',
    'your_new_field', // Add here
];
  1. Update Controller Validation:
php
$validated = $request->validate([
    // ... existing fields
    'your_new_field' => 'nullable|string',
]);
  1. Update Vue Component: Add the field to the form in Branches.vue.

Styling Customization ​

The component uses Tailwind CSS classes. Modify styling in:

vue
<Card class="relative hover:shadow-lg transition-shadow">

Adding Permissions ​

Implement role-based access:

php
// In BranchController.php
public function __construct()
{
    $this->middleware('role:admin');
}

Troubleshooting ​

Branch Not Appearing After Creation ​

  • Check browser console for JavaScript errors
  • Verify database connection
  • Check validation errors in network tab

Cannot Delete Branch ​

  • Error message will indicate if users are assigned
  • Reassign users to different branches first
  • Check database foreign key constraints

Form Not Submitting ​

  • Check required fields are filled
  • Verify network connection
  • Check Laravel logs for validation errors

Flash Messages Not Showing ​

  • Ensure flash messages are shared in Inertia middleware
  • Check component implementation of Alert components

Best Practices ​

  1. Branch Codes: Use consistent naming (e.g., MAIN, DWTN, NORTH)
  2. Addresses: Include complete address with city and postal code
  3. Contact Info: Always provide at least phone or email
  4. Status Management: Deactivate instead of delete when possible
  5. User Assignment: Reassign users before deleting branches

Future Enhancements ​

Potential features to add:

  1. Branch Statistics Dashboard

    • Patient count per branch
    • Revenue metrics
    • Appointment statistics

  2. Branch Settings

    • Operating hours configuration
    • Service types offered
    • Capacity management

  3. Bulk Operations

    • Import branches from CSV
    • Bulk activate/deactivate
    • Export branch data

  4. Advanced Search

    • Filter by active status
    • Sort options
    • Pagination for large datasets

  5. Branch Details Page

    • Dedicated page per branch
    • Assigned staff list
    • Branch-specific settings
    • Performance metrics

Support ​

For issues or questions:

  • Check Laravel logs: storage/logs/laravel.log
  • Check browser console for frontend errors
  • Review validation errors in network tab
  • Consult DATABASE_SETUP.md for database-related issues

CPR - Clinical Patient Records

CPR Development Team