Guide Management

Overview Description

The Guide Management feature enables administrators to create, manage, and publish instructional content for system users. Guides provide step-by-step instructions, best practices, and contextual help that assist users in effectively utilizing the platform. Administrators can create various guides, update their content, change their visibility status, and remove outdated guides. This feature helps enhance user experience by providing accessible documentation directly within the system.

Activity Diagram

---
config:
  theme: base
  layout: dagre
  flowchart:
    curve: linear
    htmlLabels: true
  themeVariables:
    edgeLabelBackground: "transparent"
---
flowchart TD
    %% Main components
    AdminUser[Admin User]
    AdminInterface[Guide Management Interface]
    ActionSelect{Action Selection}
    
    %% Action components
    ViewGuides[List Guides]
    GuideDetails[Guide Details]
    CreateForm[Guide Creation Form]
    EditForm[Guide Edit Form]
    ToggleStatus[Toggle Guide Status]
    DeleteConfirm{Confirm Deletion}
    
    %% Processing components
    ValidateCreate{Validate Input}
    ValidateEdit{Validate Input}
    SaveGuide[Save Guide to Database]
    UpdateGuide[Update Guide in Database]
    UpdateStatusDB[Update Status in Database]
    DeleteFromDB[Delete from Database]
    
    %% Flow connections with numbered steps
    AdminUser --- Step1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>1</span>
            <p style='margin-top: 8px'>Access Interface</p>
        </div>
    ]
    Step1 --> AdminInterface
    
    AdminInterface --- Step2[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>2</span>
            <p style='margin-top: 8px'>Select Action</p>
        </div>
    ]
    Step2 --> ActionSelect
    
    ActionSelect --- Step3A[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3A</span>
            <p style='margin-top: 8px'>View Guides</p>
        </div>
    ]
    Step3A --> ViewGuides
    
    ActionSelect --- Step3B[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #99cc66 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3B</span>
            <p style='margin-top: 8px'>View Details</p>
        </div>
    ]
    Step3B --> GuideDetails
    
    ActionSelect --- Step3C[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3C</span>
            <p style='margin-top: 8px'>Create Guide</p>
        </div>
    ]
    Step3C --> CreateForm
    
    ActionSelect --- Step3D[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3D</span>
            <p style='margin-top: 8px'>Update Guide</p>
        </div>
    ]
    Step3D --> EditForm
    
    ActionSelect --- Step3E[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3E</span>
            <p style='margin-top: 8px'>Change Status</p>
        </div>
    ]
    Step3E --> ToggleStatus
    
    ActionSelect --- Step3F[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc6666 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>3F</span>
            <p style='margin-top: 8px'>Delete Guide</p>
        </div>
    ]
    Step3F --> DeleteConfirm
    
    CreateForm --- Step4C[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4C</span>
            <p style='margin-top: 8px'>Validate</p>
        </div>
    ]
    Step4C --> ValidateCreate
    
    EditForm --- Step4D[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4D</span>
            <p style='margin-top: 8px'>Validate</p>
        </div>
    ]
    Step4D --> ValidateEdit
    
    ToggleStatus --- Step4E[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4E</span>
            <p style='margin-top: 8px'>Update Status</p>
        </div>
    ]
    Step4E --> UpdateStatusDB
    
    DeleteConfirm --- Step4F[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc6666 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>4F</span>
            <p style='margin-top: 8px'>Delete Record</p>
        </div>
    ]
    Step4F -->|Confirm| DeleteFromDB
    
    ValidateCreate --- Step5C1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5C</span>
            <p style='margin-top: 8px'>Save Guide</p>
        </div>
    ]
    Step5C1 -->|Valid| SaveGuide
    
    ValidateEdit --- Step5D1[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5D</span>
            <p style='margin-top: 8px'>Update Guide</p>
        </div>
    ]
    Step5D1 -->|Valid| UpdateGuide
    
    SaveGuide --- Step6C[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc66cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>6C</span>
            <p style='margin-top: 8px'>Return to Interface</p>
        </div>
    ]
    Step6C --> AdminInterface
    
    UpdateGuide --- Step6D[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc9966 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>6D</span>
            <p style='margin-top: 8px'>Return to Interface</p>
        </div>
    ]
    Step6D --> AdminInterface
    
    UpdateStatusDB --- Step5E[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #6699cc !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5E</span>
            <p style='margin-top: 8px'>Return to Interface</p>
        </div>
    ]
    Step5E --> AdminInterface
    
    DeleteFromDB --- Step5F[
        <div style='text-align: center'>
            <span style='display: inline-block; background-color: #cc6666 !important; color:white; width: 28px; height: 28px; line-height: 28px; border-radius: 50%; font-weight: bold'>5F</span>
            <p style='margin-top: 8px'>Return to Interface</p>
        </div>
    ]
    Step5F --> AdminInterface
    
    ValidateCreate -.->|Invalid| CreateForm
    ValidateEdit -.->|Invalid| EditForm
    DeleteConfirm -.->|Cancel| AdminInterface
    
    %% Styling
    style AdminUser fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style AdminInterface fill:#e6f3ff,stroke:#0066cc,stroke-width:2px
    style ActionSelect fill:#f5f0ff,stroke:#9966cc,stroke-width:2px
    style ViewGuides fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style GuideDetails fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style CreateForm fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style EditForm fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style ToggleStatus fill:#f0f8e6,stroke:#339933,stroke-width:2px
    style DeleteConfirm fill:#f5f0ff,stroke:#9966cc,stroke-width:2px
    style ValidateCreate fill:#f5f0ff,stroke:#9966cc,stroke-width:2px
    style ValidateEdit fill:#f5f0ff,stroke:#9966cc,stroke-width:2px
    style SaveGuide fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style UpdateGuide fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style UpdateStatusDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    style DeleteFromDB fill:#ffe6cc,stroke:#ff9900,stroke-width:2px
    
    style Step1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step2 fill:transparent,stroke:transparent,stroke-width:1px
    style Step3A fill:transparent,stroke:transparent,stroke-width:1px
    style Step3B fill:transparent,stroke:transparent,stroke-width:1px
    style Step3C fill:transparent,stroke:transparent,stroke-width:1px
    style Step3D fill:transparent,stroke:transparent,stroke-width:1px
    style Step3E fill:transparent,stroke:transparent,stroke-width:1px
    style Step3F fill:transparent,stroke:transparent,stroke-width:1px
    style Step4C fill:transparent,stroke:transparent,stroke-width:1px
    style Step4D fill:transparent,stroke:transparent,stroke-width:1px
    style Step4E fill:transparent,stroke:transparent,stroke-width:1px
    style Step4F fill:transparent,stroke:transparent,stroke-width:1px
    style Step5C1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step5D1 fill:transparent,stroke:transparent,stroke-width:1px
    style Step5E fill:transparent,stroke:transparent,stroke-width:1px
    style Step5F fill:transparent,stroke:transparent,stroke-width:1px
    style Step6C fill:transparent,stroke:transparent,stroke-width:1px
    style Step6D fill:transparent,stroke:transparent,stroke-width:1px

API: Guide Management API

Case Documentation

Case 1: Listing Guides

Description

Administrator retrieves a paginated list of all guides in the system.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as GuideController
    participant Repository as GuideRepository
    participant DB as Database

    Note over Admin,DB: Step 1: Request Guide List
    Admin->>API: GET /api/admin/guides (with query params)
    
    Note over API,Repository: Step 2: Retrieve Guides
    API->>Repository: paginate(params)
    Repository->>DB: Query Guides
    DB-->>Repository: Return Matching Guides
    Repository-->>API: Return Paginated Results
    
    Note over API,Admin: Step 3: Return Guide List
    API-->>Admin: 200 OK (guides collection)

Steps

Step 1: Request Guide List

• Description: Admin requests the list of guides with optional pagination
• Request: GET /api/admin/guides
• Query Parameters:
  • per_page: Number of items per page
  • page: Page number

Step 2: Retrieve Guides

• Description: System fetches guides from the database
• Action:
  • Apply pagination parameters
  • Retrieve guides in order (likely newest first)

Step 3: Return Guide List

• Description: Return the paginated list of guides
• Response:
  • Success: 200 OK with guide collection and pagination metadata
  • Error: Appropriate error message

Error Handling

• Log
  • Guide list retrieval failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  400	Generic error with exception message	When unexpected errors occur

Case 2: Viewing a Specific Guide

Description

Administrator views the details of a specific guide.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as GuideController
    participant Repository as GuideRepository
    participant DB as Database

    Note over Admin,DB: Step 1: Request Guide Details
    Admin->>API: GET /api/admin/guides/{id}
    
    Note over API,Repository: Step 2: Retrieve Guide
    API->>Repository: findById(id)
    Repository->>DB: Query by ID
    DB-->>Repository: Return Guide Data
    Repository-->>API: Return Guide
    
    Note over API,Admin: Step 3: Return Guide Details
    API-->>Admin: 200 OK (guide resource)

Steps

Step 1: Request Guide Details

• Description: Admin requests details for a specific guide
• Request: GET /api/admin/guides/{id}

Step 2: Retrieve Guide

• Description: System fetches the guide by ID
• Action: Retrieve complete guide record

Step 3: Return Guide Details

• Description: Return the guide details
• Response:
  • Success: 200 OK with guide resource
  • Error: Appropriate error message if guide not found

Error Handling

• Log
  • Guide retrieval failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  400	Generic error with exception message	When unexpected errors occur

Case 3: Creating a New Guide

Description

Administrator creates a new guide in the system.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as GuideController
    participant Service as GuideService
    participant DB as Database

    Note over Admin,DB: Step 1: Submit Guide Creation
    Admin->>API: POST /api/admin/guides (guide_data)
    
    Note over API,API: Step 2: Validate Input
    API->>API: Validate Request Data
    
    Note over API,Service: Step 3: Create Guide
    API->>Service: create(validated_data)
    Service->>DB: Store New Guide
    DB-->>Service: Return Created Guide
    
    Note over API,Admin: Step 4: Return Response
    Service-->>API: Return Guide Data
    API-->>Admin: 200 OK (guide resource)

Steps

Step 1: Submit Guide Creation

• Description: Admin submits form to create a new guide
• Request: POST /api/admin/guides
• Required fields:
  • title: Guide title
  • content: Guide content (may include formatting)
  • status: Guide visibility status
  • Other fields as required by the implementation

Step 2: Validate Input

• Description: System validates all input data
• Action: Runs validation rules from GuideCreateRequest
• Potential errors: Validation failures

Step 3: Create Guide

• Description: System creates the new guide
• Action: Store guide record in database

Step 4: Return Response

• Description: Return the created guide data
• Response:
  • Success: 200 OK with guide data
  • Error: Appropriate error message

Error Handling

• Log
  • Guide creation failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  400	Generic error with exception message	When guide creation fails

Case 4: Updating a Guide

Description

Administrator updates an existing guide.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as GuideController
    participant Service as GuideService
    participant DB as Database

    Note over Admin,DB: Step 1: Submit Guide Update
    Admin->>API: PUT /api/admin/guides/{id} (updated_data)
    
    Note over API,API: Step 2: Validate Input
    API->>API: Validate Request Data
    
    Note over API,Service: Step 3: Update Guide
    API->>Service: update(id, validated_data)
    Service->>DB: Update Guide Record
    DB-->>Service: Return Updated Guide
    
    Note over API,Admin: Step 4: Return Response
    Service-->>API: Return Guide Data
    API-->>Admin: 200 OK (guide resource)

Steps

Step 1: Submit Guide Update

• Description: Admin submits form to update guide information
• Request: PUT /api/admin/guides/{id}
• Updatable fields:
  • title: Guide title
  • content: Guide content
  • status: Guide visibility status
  • Other fields as allowed by the implementation

Step 2: Validate Input

• Description: System validates all input data
• Action: Runs validation rules from GuideUpdateRequest
• Potential errors: Validation failures

Step 3: Update Guide

• Description: System updates the guide information
• Action: Update guide record with new data

Step 4: Return Response

• Description: Return the updated guide data
• Response:
  • Success: 200 OK with updated guide data
  • Error: Appropriate error message

Error Handling

• Log
  • Guide update failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  400	Generic error with exception message	When guide update fails

Case 5: Changing Guide Status

Description

Administrator toggles the active status of a guide to control its visibility to users.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as GuideController
    participant Repository as GuideRepository
    participant DB as Database

    Note over Admin,DB: Step 1: Request Status Change
    Admin->>API: POST /api/admin/guides/{id}/change-status
    
    Note over API,Repository: Step 2: Retrieve Current Guide
    API->>Repository: findById(id)
    Repository->>DB: Query by ID
    DB-->>Repository: Return Guide Data
    
    Note over API,Repository: Step 3: Toggle Guide Status
    API->>Repository: update(id, {status: !current_status})
    Repository->>DB: Update Status
    DB-->>Repository: Return Updated Guide
    
    Note over API,Admin: Step 4: Return Response
    Repository-->>API: Return Guide Data
    API-->>Admin: 200 OK (guide resource)

Steps

Step 1: Request Status Change

• Description: Admin requests to change a guide's visibility status
• Request: POST /api/admin/guides/{id}/change-status

Step 2: Retrieve Current Guide

• Description: System retrieves the current guide to get its status
• Action:
  • Find guide by ID
  • Check if guide exists
• Potential errors: Guide not found

Step 3: Toggle Guide Status

• Description: System toggles the guide's active status
• Action:
  • Update status to opposite value (active to inactive or vice versa)

Step 4: Return Response

• Description: Return the updated guide data
• Response:
  • Success: 200 OK with updated guide data including new status
  • Error: Appropriate error message

Error Handling

• Log
  • Status change failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  404	"messages.error.not-found"	When the requested guide doesn't exist
  400	Generic error with exception message	When status update fails

Case 6: Deleting a Guide

Description

Administrator removes a guide from the system.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as GuideController
    participant Repository as GuideRepository
    participant DB as Database

    Note over Admin,DB: Step 1: Request Guide Deletion
    Admin->>API: DELETE /api/admin/guides/{id}
    
    Note over API,Repository: Step 2: Delete Guide
    API->>Repository: delete(id)
    Repository->>DB: Delete Guide Record
    DB-->>Repository: Confirm Deletion
    
    Note over API,Admin: Step 3: Return Response
    API-->>Admin: 200 OK (success message)

Steps

Step 1: Request Guide Deletion

• Description: Admin requests to delete a guide
• Request: DELETE /api/admin/guides/{id}

Step 2: Delete Guide

• Description: System removes the guide from the database
• Action: Delete guide record

Step 3: Return Response

• Description: Confirm successful deletion
• Response:
  • Success: 200 OK with success message
  • Error: Appropriate error message if deletion fails

Error Handling

• Log
  • Guide deletion failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  400	Generic error with exception message	When deletion fails

Case 7: Retrieving Active Guides List

Description

Administrator retrieves a list of only active guides for reference.

Sequence Diagram

sequenceDiagram
    participant Admin
    participant API as GuideController
    participant Repository as GuideRepository
    participant DB as Database

    Note over Admin,DB: Step 1: Request Active Guides
    Admin->>API: GET /api/admin/guides/active
    
    Note over API,Repository: Step 2: Retrieve Active Guides
    API->>Repository: findByField({status: Active})
    Repository->>DB: Query Active Guides
    DB-->>Repository: Return Active Guides
    
    Note over API,Admin: Step 3: Return Active Guides List
    API-->>Admin: 200 OK (guides collection)

Steps

Step 1: Request Active Guides

• Description: Admin requests list of only active guides
• Request: GET /api/admin/guides/active

Step 2: Retrieve Active Guides

• Description: System fetches only active guides from the database
• Action: Query guides with Active status

Step 3: Return Active Guides List

• Description: Return the list of active guides
• Response:
  • Success: 200 OK with active guides collection
  • Error: Appropriate error message

Database Related Tables & Fields

erDiagram
    guides {
        bigint id PK "Primary key"
        string category_name "Category name of the guide"
        string icon "Icon for the guide (nullable)"
        string title "Guide title"
        text content "Guide content"
        bigint created_by FK "User ID who created the guide"
        tinyint status "Guide status: 1=Active, 0=Inactive"
        timestamp created_at "Creation timestamp"
        timestamp updated_at "Last update timestamp (nullable)"
        timestamp deleted_at "Soft delete timestamp (nullable)"
    }
    users {
        bigint id PK "Primary key"
        string name "User's name"
        string email "User's email"
        timestamp created_at "Creation timestamp"
        timestamp updated_at "Last update timestamp"
    }

    guides ||--o{ users : "created_by"

Error Handling

• Log
  • Guide list retrieval failures logged to application log
• Error Detail:

  Status Code	Error Message	Description
  400	Generic error with exception message	When unexpected errors occur

Additional Notes

• The Guide Management feature supports formatted content to enhance readability
• Active status toggles control the visibility of guides to end users
• Guides can be used for various purposes such as onboarding instructions, feature walkthroughs, and best practices
• The Active Guides List endpoint provides a convenient way to preview what guides are currently visible to users
• Administrators can organize guides by importance and relevance through the status field