πŸ“‹ SystemAdminController Documentation

Welcome to the comprehensive documentation for SystemAdminController.cs in the IrbyImaging.UI.Controllers namespace. This guide covers every aspectβ€”from architecture and dependencies to API endpoints, view models, helper utilities, and usage examples.


Table of Contents

  1. Overview & Purpose
  2. Dependencies & Technologies
  3. Class Diagram (Mermaid UML)
  4. Key Functional Areas
  5. API Endpoints Overview
  6. View Models & Data Models
  7. Helper Methods & Utilities
  8. Error Handling & Return Types
  9. Third-party Integrations
  10. Sample Code Blocks & Usage Examples
  11. Conclusion

1. Overview & Purpose

SystemAdminController is the central MVC controller responsible for administrative tasks within the IrbyImaging UI:

  • πŸ” User / Employee Management: CRUD operations, filtering, partial views.
  • πŸ‘₯ Role Management: Create, edit, delete roles; assign/remove users and permissions.
  • πŸ”’ Permission Management: Create, edit, delete permissions; link to roles.
  • 🏒 Department Management: Organize employees into departments.
  • πŸ“Š Reporting & Auditing: Generate audit logs, access reports, and export data.

It leverages Entity Framework Core (IrbyContext) for data access and integrates with Azure AD, Blob Storage, and several internal services.


2. Dependencies & Technologies

Category Technology / Package
Framework ASP.NET Core MVC
ORM Entity Framework Core (Microsoft.EntityFrameworkCore)
Caching Microsoft.AspNetCore.OutputCaching
Cloud Storage Azure Blob Storage (Azure.Storage.Blobs)
Authentication / AD MailKit.Search, internal AzureADRead
Config & Environment Microsoft.Extensions.Configuration, IWebHostEnvironment
JSON Serialization Newtonsoft.Json
UI Models & Services IrbyImaging.UI.Models, IrbyImaging.UI.Services
Domain & Business Logic IrbyImaging.DomainClasses, IrbyImaging.BusinessLogic
Utilities IrbyImaging.Utility, SKiaSharp.HarfBuzz

3. Class Diagram (Mermaid UML)

classDiagram
    class SystemAdminController {
        - IrbyContext _context
        - Employee _employee
        - IHttpContextAccessor _httpContextAccessor
        - IUploadService _uploadService
        - IWebHostEnvironment _hostingEnvironment
        - BlobServiceClient _blobServiceClient
        - IConfiguration _configuration
        + SystemAdminController(...)
        + AdminMenu()
        + ViewEmployees()
        + AuditReport()
        + ViewEmployeeDetails(Guid)
        + AccessReport()
        + Filter(string, bool?)
        + FillUsersTable(RoleBasedAccess)
        + UserDetails(Guid)
        + UserEdit(Guid) [GET/POST]
        + DeleteUserRole(...)
        + ... (many more)
    }
    SystemAdminController --> IrbyContext
    SystemAdminController --> IHttpContextAccessor
    SystemAdminController --> IWebHostEnvironment
    SystemAdminController --> IUploadService
    SystemAdminController --> BlobServiceClient
    SystemAdminController --> IConfiguration
    SystemAdminController ..> Employee
    SystemAdminController ..> Role
    SystemAdminController ..> Department
    SystemAdminController ..> Permissions
    SystemAdminController ..> LinkUserRole
    SystemAdminController ..> LinkRolePermission

4. Key Functional Areas

4.1 Employee Management πŸ‘₯

  • View & List

    • ViewEmployees() β†’ Displays active employees.
    • Filter(string FilterBy, bool? showTerminated) β†’ Search by LastName or GUID, optional include terminated.
  • Details & Edit

    • ViewEmployeeDetails(Guid Id) β†’ Full profile with Dept/Role/Job and linked roles.
    • UserDetails(Guid id) / UserEdit(Guid id) β†’ GET/POST edit forms.
  • Partial Updates

    • filter4Users(string surname) / filterReset() β†’ AJAX filtering.
    • DeleteUserReturnPartialView(Guid userId) β†’ Marks user record modified.

4.2 Role Management βš™οΈ

  • CRUD Operations

    • RoleIndex(), RoleDetails(Guid), RoleCreate(), RoleEdit(Guid), RoleDelete(Guid).
  • Assignment

    • AddUser2RoleReturnPartialView(Guid roleId, Guid userId)
    • DeleteUserFromRoleReturnPartialView(Guid roleId, Guid userId)
  • Export

    • ExportRole(Guid) β†’ JSON dump of a role’s permissions and assignments.

4.3 Permission Management πŸ”’

  • CRUD Operations

    • PermissionIndex(), PermissionDetails(Guid), PermissionCreate(), PermissionEdit(Guid), PermissionDelete(Guid).
  • Linking to Roles

    • AddPermission2RoleReturnPartialView(Guid roleId, List<string> permissionIds)
    • DeletePermissionFromRoleReturnPartialView(Guid roleId, Guid permissionId)
  • Reverse Linking

    • AddRole2PermissionReturnPartialView(Guid permissionId, Guid roleId)
    • DeleteRoleFromPermissionReturnPartialView(Guid permissionId, Guid roleId)

4.4 Department Management 🏒

  • CRUD & Details

    • DepartmentIndex(), DepartmentDetails(Guid), DepartmentCreate(string, string, List<string>), DepartmentEdit(Guid).
  • Modals

    • departmentModalRole(Guid), departmentModalEmployee(Guid)

4.5 Reporting & Analytics πŸ“Š

  • Audit Trail

    • AuditReport() β†’ SQL-based audit log with join on Employee, Role, Department.
  • Access Reports

    • AccessReport() β†’ Per-user permission summary.
    • GetEmployeeRolesAndPermissionsReport() β†’ Exportable list.
    • GetRolesAndPermissionsReport() β†’ Global view by role/permission.

5. API Endpoints Overview

Action Method HTTP Verb Route (convention) Description
AdminMenu() GET /SystemAdmin/AdminMenu Landing page for admin menu.
ViewEmployees() GET /SystemAdmin/ViewEmployees List non-terminated employees.
AuditReport() GET /SystemAdmin/AuditReport Audit trail report.
ViewEmployeeDetails(Guid id) GET /SystemAdmin/ViewEmployeeDetails/{id} Detailed employee profile.
AccessReport() GET /SystemAdmin/AccessReport System access summary per user.
Filter(string, bool?) GET /SystemAdmin/Filter Employee search/filter.
RoleCreate(), RoleEdit(), RoleDelete() GET/POST /SystemAdmin/{RoleAction} Role CRUD operations.
PermissionCreate(), PermissionEdit(), PermissionDelete() GET/POST /SystemAdmin/{PermissionAction} Permission CRUD.
DepartmentCreate(), DepartmentEdit(), DepartmentDelete() GET/POST /SystemAdmin/{DepartmentAction} Department CRUD.
ExportRole(Guid id) GET /SystemAdmin/ExportRole/{id} Download role JSON.
PartialViewResult …ReturnPartialView(...) GET AJAX Dynamic partial views for UI updates.

6. View Models & Data Models

Model / DTO Purpose
Employee Domain entity for staff.
Role System role with description.
Permissions Individual permission.
Department Organizational unit.
LinkUserRole Junction table for extra role assignments.
LinkRolePermission Junction table for role-permission links.
UserAccessReport DTO for AccessReport view.
SystemAccessList DTO for exportable roles/permissions report.
RoleBasedAccess Container for users table filtering.

7. Helper Methods & Utilities πŸ› 

  • SetViewBagData(Guid userId)
    Populates ViewBag with select lists for roles, departments, boolean flags.

  • List_boolNullYesNo()
    Returns a List<SelectListItem> for tri-state filters: Not Set / Yes / No.

  • GetFilteredUserList(string surname)
    Safely queries employees by LastName.

  • Dispose(bool disposing)
    Ensures IrbyContext is properly disposed.


8. Error Handling & Return Types

  • Try/Catch Blocks: Used in partial view updates to swallow exceptions and maintain UI stability.
  • ModelState Validation: On POST edits for Role and Permissions, validating required fields.
  • Return Types:
    • ActionResult: Full-page views & redirects.
    • ViewResult: Strongly-typed views.
    • PartialViewResult: AJAX partial updates.
    • IActionResult / FileResult: File downloads & JSON returns.

9. Third-party Integrations πŸ”—

  • Azure AD via AzureADRead for retrieving current user details.
  • Azure Blob Storage through BlobServiceClient (future file uploads).
  • MailKit (imported but not directly used here) for email-related searches.
  • SKiaSharp.HarfBuzz (imported but reserved for future graphical operations).

10. Sample Code Blocks & Usage Examples πŸš€

10.1 Calling the Audit Report

// Controller action:
public IActionResult AuditReport()
{
    var records = _context.AuditReport
        .FromSqlInterpolated($"SELECT ... ORDER BY ActivityDate DESC")
        .ToList();

    ViewBag.datasource = records;
    return View();
}

10.2 Filtering Users by Surname via AJAX

// JavaScript fetch:
fetch(`/SystemAdmin/filter4Users?surname=Smith`)
  .then(res => res.text())
  .then(html => document.querySelector('#usersTable').innerHTML = html);

10.3 Exporting a Role as JSON

public ActionResult ExportRole(Guid id)
{
    var json = AccessControl.ExportRole(id, _context, out var name);
    return File(Encoding.UTF8.GetBytes(json), "application/json", $"{name}.json");
}

11. Conclusion

The SystemAdminController orchestrates the administrative backbone of the IrbyImaging UIβ€”managing employees, roles, permissions, departments, and critical reports. Its modular design with clean separation of view models, helper utilities, and partial views allows for scalable enhancements and responsive UI updates.

Use this documentation as your go-to reference for extending, debugging, or integrating new features into the System Administration area. Happy coding! πŸš€