# BV-SIS Phase 1 — CRUD Operations Report

**Module:** Institution Setup  
**Date:** 9 July 2026  

---

## CRUD Architecture

### Base Trait: `HandlesInstitutionCrud`

All list-based modules use a shared controller trait providing:

| Method | HTTP | Route Suffix | Description |
|--------|------|--------------|-------------|
| index | GET | `/` | Paginated list with filters |
| create | GET | `/create` | Create form |
| store | POST | `/` | Save new record |
| show | GET | `/{id}` | View record details |
| edit | GET | `/{id}/edit` | Edit form |
| update | PUT | `/{id}` | Update record |
| destroy | DELETE | `/{id}` | Soft delete |
| restore | POST | `/{id}/restore` | Restore soft-deleted |
| duplicate | POST | `/{id}/duplicate` | Clone record |
| archive | POST | `/{id}/archive` | Set status archived |
| activate | POST | `/{id}/activate` | Set status active |
| deactivate | POST | `/{id}/deactivate` | Set status inactive |
| bulkDelete | POST | `/bulk-delete` | Bulk soft delete |
| bulkArchive | POST | `/bulk-archive` | Bulk archive |
| export | GET | `/export` | CSV download |
| print | GET | `/{id}/print` | Print-friendly view |

### Base Repository: `BaseInstitutionRepository`

Provides data access with:
- `paginate($filters)` — search, status, trashed, parent FK filters
- `all($filters)` — for exports
- `create`, `update`, `delete`, `restore`, `forceDelete`
- `bulkDelete`, `bulkArchive`, `bulkActivate`, `bulkDeactivate`
- `countByStatus()` — for statistics cards

### Model Trait: `HasInstitutionRecord`

- Auto UUID generation
- Default active status
- Scopes: `active`, `inactive`, `archived`, `search`
- Methods: `activate()`, `deactivate()`, `archive()`, `duplicateRecord()`

---

## Per-Module CRUD Matrix

| Module | Create | Read | Update | Delete | Restore | Duplicate | Archive | Activate | Deactivate | Bulk Del | Bulk Arch | Export | Print |
|--------|--------|------|--------|--------|---------|-----------|---------|----------|------------|----------|-----------|--------|-------|
| Institution | — | ✅ | ✅ | — | — | — | — | ✅ | ✅ | — | — | — | — |
| Campuses | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Faculty | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Area of Study | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Programmes | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Programme Tracks | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Programme Structure | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Academic Path | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Sessions | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Study Plan Periods | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Academic Intake | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| Dashboard | — | ✅ | — | — | — | — | — | — | — | — | — | — | — |

---

## Validation

All write operations use Laravel Form Requests:

- `Store*Request` — create validation with unique constraints
- `Update*Request` — update validation with unique ignore
- Enum validation via `Rule::enum()`
- JSON fields validated as arrays
- Nested `items.*` validation for programme structure courses

---

## Authorization

Each model has a Policy extending `InstitutionPolicy`:

| Policy | Permission Prefix |
|--------|-------------------|
| InstitutionModelPolicy | institution.institution |
| CampusPolicy | institution.campuses |
| FacultyPolicy | institution.faculty |
| AreaOfStudyPolicy | institution.area_of_study |
| ProgrammePolicy | institution.programme_of_study |
| ProgrammeTrackPolicy | institution.programme_track |
| ProgrammeStructurePolicy | institution.programme_structure |
| AcademicPathPolicy | institution.academic_path |
| AcademicSessionPolicy | institution.sessions_setup |
| StudyPlanPeriodPolicy | institution.study_plan_periods |
| AcademicIntakePolicy | institution.academic_intake |

`super_admin` role bypasses all checks via `Gate::before`.

---

## Audit Trail

- **Spatie Activity Log:** All model changes logged via `LogsInstitutionActivity` trait
- **AuditService:** Custom file-based audit log for controller actions
- **Audit fields:** `created_by`, `updated_by` on all records

---

## Special Implementations

### Institution Profile
- Single-record store (not list CRUD)
- Logo and favicon upload to `storage/app/public/institution`
- Tabbed form: General, Contact, Branding, Email, SMS, Documents

### Programme Structure
- Nested course items synced on create/update
- Visual course allocation with prerequisites JSON
- Level and semester builder

### Academic Path
- JSON rules: progression, promotion, graduation
- Optional programme track association

### Academic Session
- `setAsCurrent()` ensures only one current session per institution
- Holiday periods as JSON array

### Duplicate
- Generates new UUID
- Appends "-COPY-XXXX" to code
- Appends " (Copy)" to name
- Sets status to draft

---

## Export Format

CSV export via `TableExportService`:
- Module-specific headers and row mapping
- Filtered by current search/status parameters
- Filename: `{route-prefix}-export.csv`

---

*BV-SIS CRUD Report — Institution Setup Phase 1*