PhoenixKitStaff

A PhoenixKit plugin that adds departments, teams, and staff profiles to a Phoenix app. Each staff profile is linked 1:1 to a PhoenixKit user; people not yet in your system can be added via a placeholder user that auto-links when they later register or sign in via OAuth.

Features

• Departments and teams with cascading deletes
• Staff profiles with employment metadata, birthdays, emergency contacts
• Skills — a translatable skill taxonomy with per-skill, optional proficiency levels (each skill defines its own levels; single- or multi-select per skill), assigned to people many-to-many
• Org tree view (departments → teams → people)
• Upcoming-birthdays widget
• Placeholder-user flow for inviting people who don't yet have an account
• Real-time updates via PhoenixKit.PubSub.Manager
• Activity logging for every mutation
• Admin pages under /admin/staff/*

Installation

Add to your parent PhoenixKit app's mix.exs:

{:phoenix_kit_staff, path: "../phoenix_kit_staff"}
# or, once published to Hex:
{:phoenix_kit_staff, "~> 0.8"}

Also add :phoenix_kit_staff to extra_applications so PhoenixKit.ModuleDiscovery finds it:

def application do
  [extra_applications: [:logger, :phoenix_kit, :phoenix_kit_staff]]
end

Run mix deps.get, then toggle the module on from Admin > Modules.

Database

Tables are created by versioned migrations inside phoenix_kit core (V100 for the base tables, V135 for skills). The parent app runs migrations via mix phoenix_kit.install / mix phoenix_kit.update.

Tables created:

• phoenix_kit_staff_departments
• phoenix_kit_staff_teams (FK → departments, cascading delete)
• phoenix_kit_staff_people (FK → phoenix_kit_users, cascading delete)
• phoenix_kit_staff_team_memberships (join table)
• phoenix_kit_staff_skills (V135 — translatable, carries its own levels JSONB + allow_multiple_levels)
• phoenix_kit_staff_person_skills (V135 — person ↔ skill join; a proficiency_levels JSONB array of the skill's selected level ids)

All tables use UUIDv7 primary keys.

Public API

# Departments
PhoenixKitStaff.Departments.list/1
PhoenixKitStaff.Departments.get/1
PhoenixKitStaff.Departments.create/1
PhoenixKitStaff.Departments.update/2
PhoenixKitStaff.Departments.delete/1

# Teams
PhoenixKitStaff.Teams.list/1        # accepts :department_uuid filter
PhoenixKitStaff.Teams.create/1      # requires department_uuid

# Staff (people + team memberships + org tree)
PhoenixKitStaff.Staff.list_people/1
PhoenixKitStaff.Staff.get_person_by_user_uuid/2
PhoenixKitStaff.Staff.create_person_with_user/2  # find-or-create placeholder user
PhoenixKitStaff.Staff.org_tree/0
PhoenixKitStaff.Staff.upcoming_birthdays/1
PhoenixKitStaff.Staff.add_team_person/2
PhoenixKitStaff.Staff.remove_team_person/2

# Skills (taxonomy + per-skill levels + assignment)
PhoenixKitStaff.Skills.list/1
PhoenixKitStaff.Skills.create/1                  # accepts levels + allow_multiple_levels
PhoenixKitStaff.Skills.update/2                  # reconciles assignments on level changes
PhoenixKitStaff.Skills.assign_skill/3            # (person_uuid, skill_uuid, level_ids)
PhoenixKitStaff.Skills.update_assignment_levels/2
PhoenixKitStaff.Skills.list_for_person/1
PhoenixKitStaff.Skills.list_people_for_skill/1

Consumed by other plugins

phoenix_kit_projects uses list_people/1, get_person_by_user_uuid/2, Teams.list/1, and Departments.list/1 for assignee pickers. Keep the public API stable.

Development

See AGENTS.md for development conventions, test setup, and the pre-commit workflow.

License

MIT