Teams

A standalone CRUD module that organizes administrators into named teams, each with a designated leader and department.

Overview

The Teams module was introduced to replace the legacy boss_id relationship on the administrators table. Instead of pointing a single "boss" at another administrator, the model now links every administrator to a team via team_id. This makes it possible to group administrators by function or area, assign an explicit team leader, and derive the administrator's department from the team rather than setting it independently.

The module covers two responsibilities: managing teams through a dedicated CRUD interface at /teams, and enforcing team assignment as a required field when creating or editing an administrator. When a user selects a team in the Administrator form, the team's department_id is automatically propagated to the form's department field, eliminating the need for the user to set it manually.

Key Concepts

Concept	Description
Team	A named group with a description, a leader, a department, and an active/inactive status
Team Leader (admin_id)	Any administrator; there is no role or level restriction on who can lead a team
Department (department_id)	The department the team belongs to; auto-applied to any administrator assigned to the team
team_id	Foreign key on administrators; required when creating or editing an administrator
teams-table / teams-add / teams-edit	Dedicated permissions that gate the Teams module independently from Administrators

Data Flow

Create an administrator with a team

The critical behavior is the frontend-side department auto-fill: no extra API call is made — the team's department_id is already included in the /catalog/teams catalog response and applied locally.

Teams CRUD flow

Database

Tables

Table	Purpose
teams	Stores team definitions (name, description, leader, department, active flag)
administrators	References teams.id via team_id (required FK since the feature launch)
departments	Provides department metadata joined into team queries

Schema — teams

Column	Type	Notes
id	int PK	Auto-increment
name	varchar(50)	Required, display name
description	varchar(100)	Optional
admin_id	int FK → administrators.id	Team leader
department_id	int FK → departments.id	Nullable
active	BIT(1)	1 = active, 0 = inactive
created_at	datetime	Set on insert

BIT(1) quirk

MySQL returns BIT(1) columns as a Buffer object in Node.js, not a number. The backend query in teams.util.js casts it with t.active + 0 AS active to ensure a numeric 0 or 1 is returned. The frontend further normalizes any residual edge cases via the normalizeActive utility in Table.vue.

Entity relationships

Legacy field

administrators.boss_id is retained in the database for historical data but is no longer read or written by any application code. It was replaced entirely by team_id.

Key Decisions

Decision	Reasoning	Alternatives Considered
team_id replaces boss_id	A team-based model naturally groups many administrators together and separates the "who manages the group" concern (leader) from the "which group" concern (team)	Keeping boss_id as a direct supervisor link
Department auto-filled from the team on the frontend	Keeps the administrator's department consistent with their team without a round-trip; all catalog data is already available	Letting the user override the department independently; server-side derivation
Dedicated permissions (teams-table, teams-add, teams-edit)	Allows granting Teams access independently from Administrators access in the future, even though currently both are granted together	Reusing administrators-* permissions entirely (done during initial implementation, reverted to separate permissions)
/catalog/teams retains administrators-table permission	The catalog endpoint is consumed by the Administrators module (not the Teams module) to fill the team_id dropdown in the administrator form; anyone who can view administrators must be able to fetch this catalog	Creating a separate teams-catalog permission
Offcanvas + FormGenerator pattern	Consistent with every other create/edit panel in the platform; eliminates boilerplate validation and layout work	Custom modal component

Dependencies

• Internal:
  • Administrators module (administratorsV2) — consumes teamsCatalog via provide/inject; team_id is a required field on the administrator form.
  • Catalogs (/catalog/teams) — read by administratorsV2/index.vue to populate the teams dropdown.
  • Auth/Permissions middleware — permissionMiddleware.canByName on every Teams route.
• External: None.

Related Documentation

• User Guide: Teams Guide — End-user instructions for managing teams and assigning them to administrators.
• API Endpoints: Teams API — Endpoint reference for developers.
• UI Screens: Teams UI — Frontend file tree, component responsibilities, and permission gates.