Docs / Categories

Category Module

The Category module provides a simple and organized way to manage categories inside the application. It supports full CRUD operations, bulk deletion, filters, and Laravel pagination. The interface is built on top of the Vendventory admin interface and supports both light mode and dark mode for a consistent admin experience.

Modernization update: categories now also store governance defaults such as batch-required, expiry-required, FEFO-required, cold-chain-required, default quality template, and default compliance template. These defaults help products inherit the right operating posture instead of being configured from scratch every time.

Version note: Only 1-level nesting is supported in this version. A category can have one parent category, but deeper multi-level nesting is not available yet. Additional nesting levels may be added in future releases.

Overview

This module is used to organize records in a structured way. Categories can be created as standalone items or assigned under a single parent category. The listing page helps administrators manage records efficiently through filters, row actions, and bulk actions. Laravel pagination is used so the page remains clean and scalable when the number of records increases.

Category module listing page in light mode — Index Light Mode

Category module listing page in dark mode — Index Dark Mode

Main purpose
Helps administrators create, organize, sort, activate, deactivate, and manage category records from one centralized interface.

Light and dark support
The module is designed to work properly in both light mode and dark mode layouts.

Core Features

Governance defaults now available in category CRUD

Batch Required: sets the default expectation for batch-controlled products in the category.
Expiry Required: controls whether expiry-aware behavior should be the default.
FEFO Required: marks categories that should default into FEFO-driven issue behavior.
Cold Chain Required: flags temperature-sensitive categories by default.
Default Quality Requirement Template: links governed categories to a release template.
Default Compliance Template: stores the expected evidence or compliance pack name for the category.

Included Functionality

Create: Add a new category with all supported fields such as parent, name, slug, description, image, order, status, and SEO values.
Read / List: View all categories in a clean tabular listing with pagination.
Update: Edit existing category records whenever changes are needed.
Delete: Remove a single category record from the system.
Bulk Delete: Select multiple records from the table and delete them together.
Filters: Use filter options to narrow down the list and find records faster.
Laravel Pagination: Keeps large category listings manageable and improves usability.
Soft Deletes: Category records are soft deleted, which helps avoid immediate permanent loss.
Dark Mode Support: The module UI also supports dark mode for users who prefer low-light interfaces.

Architecture

The Category module follows a layered structure to keep the codebase clean, scalable, and easier to maintain. Instead of placing all logic inside a single controller, responsibilities are separated across multiple layers.

Layered Structure Used

Controller: Handles incoming requests, returns views or responses, and coordinates module flow.
Service: Contains the main business logic of the Category module.
Repository: Manages data access and database-related operations in a structured way.
Repository Interface: Defines the contract used by the repository layer, making the module easier to extend and maintain.
Model: Represents the categories table and its relationships, including the parent category relation.

This layered approach keeps controllers cleaner and separates business logic from database operations for better maintainability.

Permissions & Security

Permissions are already present in the application and are also applied to the Category module. The system uses Spatie Laravel Permission with a multi-layered approach, so access control is enforced at more than one point.

How Permission Checks Are Applied

Menu Items: Navigation items are shown or hidden according to assigned permissions.
Controllers: Controller methods are protected so unauthorized users cannot access restricted actions.
Requests: Request classes also apply authorization checks before processing data.
Spatie Laravel Permission: Roles and permissions across the module are managed using Spatie's package.

Even if a user tries to access a route manually, layered permission checks still help prevent unauthorized actions.

Database Structure

The Category module stores its data in the categories table. The table is designed to support parent-child relationships, sorting, activation status, SEO values, timestamps, and soft deletes.

Field Explanation

id: The primary key of the table. Each category record has its own unique identifier.
parent_id: An optional self-relation field that links the current category to another category as its parent. In this version, only one nesting level is allowed.
name: The main display name of the category. This is the value users usually see in forms and listings.
slug: A unique URL-friendly version of the category name used for cleaner URLs and consistency.
description: An optional text field used to describe the category in more detail.
image: An optional image path or file reference for category thumbnails, icons, or related visuals.
sort_order: A numeric field used to control how categories are arranged in the listing.
is_active: A boolean field that determines whether the category is active or inactive.
meta_title: An optional SEO field used for custom metadata title values.
meta_description: An optional SEO field used for custom metadata description values.
created_at: Stores the date and time when the category was created.
updated_at: Stores the date and time when the category was last updated.
deleted_at: Used for soft deletes. When this field contains a value, the record is treated as deleted without being permanently removed.

Indexes

Performance-Related Indexes

Index on parent_id and is_active: Helps improve queries that depend on parent category and active status.
Index on name: Helps improve lookups and filtering based on category name.

These indexes help keep retrieval and filtering faster as category records grow.

Listing Page

The listing page is designed for daily administrative use. It allows users to browse category records, apply filters, use row-level actions, and perform bulk deletion where permitted. Laravel pagination ensures the interface remains readable and practical.

Listing Screen Highlights

Paginated table: Keeps the interface clean when many records exist.
Filter support: Helps narrow down records quickly based on selected criteria.
Bulk selection: Multiple records can be selected for bulk deletion.
Action controls: Common row actions such as edit and delete are available according to permission.
Status visibility: Active and inactive categories can be identified more easily in the table.

Category create or edit form in light mode

Category create or edit form in dark mode

Nesting Rules

Current Nesting Behavior

A category may exist without any parent category.
A category may also be assigned to one parent category.
Only one nesting level is supported in this release.
Multi-level hierarchies such as parent, child, and grandchild are not yet supported.
Further nesting depth may be introduced in future releases.

Important Notes

Things to Remember

The slug field must remain unique.
The parent category is optional.
Soft deletes are enabled for safer record handling.
Permissions are enforced through menu, controller, and request layers.
Both light mode and dark mode are supported in the UI.
Only one-level nesting is supported in the current version.

The Category module is intentionally kept simple in this release so it remains stable, easy to understand, and practical for most common use cases.

Screen-by-Screen Category Breakdown

What each category screen does

Category listing page: browse existing categories, check hierarchy, and review the naming structure used by products.
Create category: add a new category name, optional parent, notes, and governance defaults that new products can inherit.
Edit category: correct naming, parent placement, or default governance behavior after the category is already in use.
Governance defaults area: this is where the category starts influencing product behavior for batch, expiry, FEFO, and related operational rules.
Why it matters: categories are no longer only labels for grouping. They now help standardize how products behave when users do not configure every governance field manually.