---
title: Team Directory with Per-Member Task Backlog
slug: team-task-backlog
category: Data
summary: A /team directory of member cards, each linking to a per-member task backlog — Backlog/Completed tabs, priority sort, an inline add form, one-click completion tickboxes, and drag-and-drop reordering persisted via SortableJS + one Stimulus controller.
tags: [stimulus, sortablejs, drag-and-drop, tasks, tabs, hotwire, turbo]
status: stable
visibility: public
source_project: duke-homes.leo.llamapress.ai
layers: [model, sql, controller, view, stimulus_js]
related:
- title: High-Quality Inline-Editable Table
url: /cookbook/inline-editable-table
summary: The sibling pattern for editing flat rows in place — this guide's card list is the better fit when rows are tasks with a lifecycle.
- title: Async Action Feedback
url: /cookbook/async-action-feedback
summary: Same fetch-with-CSRF pattern this guide's reorder POST uses, with fuller UX feedback treatment.
---
# Team Directory with Per-Member Task Backlog
> ⚠️ **Cookbook example — not live code.** (KEEP THIS CALLOUT.) Every code block below
> is an **example snippet**, **not part of the llamapress.ai codebase**, and **not
> running on this server**. This is a reference recipe for a **Leo instance (an AI coding
> agent) to implement in its own app** — read it to understand the pattern, then recreate
> it there.
A lightweight, iPhone-Reminders-style task system hung off a team directory. `/team`
shows a card grid of members (avatar, title, open-task count badge, a **Tasks** button);
`/team/:id/tasks` is that member's backlog: an inline "Add a task…" form, task cards
with a completion tickbox, priority dot, optional deadline and expandable details, a
**Backlog / Completed** tab toggle, a **Manual / Priority** sort toggle, and
drag-and-drop reordering that persists across reloads.
> **When to use:** any "who's doing what" screen — team to-dos, per-client action items,
> per-project checklists. The pattern generalizes to *any parent with an ordered list of
> checkable children*. **When not to:** full project management (dependencies, statuses
> beyond done/not-done, multiple assignees per task) — that wants real state machines,
> not a boolean.
> The example uses `User` as the team member ("assignee") and a new `Task` model.
> Swap the parent for any model — see **How to adapt** at the bottom.
---
## The 80/20 in one breath
1. A `tasks` table: `user_id` (assignee), `description`, `priority`, `completed`,
`completed_at`, `position` (manual order), optional `deadline` + `details`.
2. Model scopes that encode the two orderings — `manual_order` (by `position`) and
`by_priority` (a SQL `CASE` on the priority string) — plus a `persist_order!` class
method that rewrites positions from an id array.
3. Two controllers: `TeamController#tasks` renders one member's list (reading
`?tab=` and `?sort=` params); `TasksController` handles create / toggle / destroy /
reorder.
4. One view with the tab + sort toggles as plain GET links (server-side state, no JS),
the add form, and the card list. The tickbox is a one-field `form_with` that flips
`completed`.
5. One Stimulus controller wrapping **SortableJS**: on drop, collect the `data-task-id`s
top-to-bottom and `fetch` POST them to `/tasks/reorder`.
Steps 1–4 are a complete task system with no JavaScript at all. Step 5 adds drag-and-drop.
---
## Layer 1 — Model & SQL
The migration (one migration; the source project shipped it as two):
```ruby
# db/migrate/XXXX_create_tasks.rb
class CreateTasks < ActiveRecord::Migration[7.2]
def change
create_table :tasks do |t|
# Who the task is assigned to (whose backlog it shows up in).
t.references :user, null: false, foreign_key: true
# Who created it (optional if your app has open auth).
t.references :creator, foreign_key: { to_table: :users }
t.text :description, null: false
t.string :priority, null: false, default: "medium"
t.boolean :completed, null: false, default: false
t.datetime :completed_at
t.integer :position # manual drag-and-drop order (per assignee)
t.datetime :deadline # optional due date
t.text :details # optional longer notes, revealed on expand
t.timestamps
end
add_index :tasks, %i[user_id completed]
add_index :tasks, %i[user_id position]
end
end
```
The model — the ordering scopes and the reorder writer are the heart of the pattern:
```ruby
# app/models/task.rb
class Task < ApplicationRecord
PRIORITIES = %w[low medium high].freeze
belongs_to :user # assignee
belongs_to :creator, class_name: "User", optional: true
validates :description, presence: true
validates :priority, inclusion: { in: PRIORITIES }
before_validation :default_priority
before_create :assign_position
before_save :stamp_completion
scope :incomplete, -> { where(completed: false) }
# Manual (drag-and-drop) order: by persisted position; newest first as a
# tiebreaker for any rows without a position yet.
scope :manual_order, -> { order(Arel.sql("position ASC NULLS LAST, created_at DESC")) }
# Priority order: high → medium → low, then manual position within a priority.
scope :by_priority, lambda {
order(
Arel.sql("CASE priority WHEN 'high' THEN 0 WHEN 'medium' THEN 1 WHEN 'low' THEN 2 ELSE 3 END ASC"),
Arel.sql("position ASC NULLS LAST")
)
}
# Finished items, most-recently-completed first.
scope :done, -> { where(completed: true).order(Arel.sql("completed_at DESC NULLS LAST, updated_at DESC")) }
# Persist a new drag-and-drop order. `ordered_ids` is the full id list
# top-to-bottom; each row's position is rewritten to match. Ids outside
# `scope` are ignored so a stray/foreign id can't touch other rows.
def self.persist_order!(ordered_ids, scope: all)
ids = Array(ordered_ids).map(&:to_i)
owned = scope.where(id: ids).pluck(:id).to_set
transaction do
ids.select { |id| owned.include?(id) }.each_with_index do |id, index|
where(id: id).update_all(position: index + 1)
end
end
end
private
def default_priority
self.priority = "medium" if priority.blank?
end
# Append new tasks to the bottom of the assignee's list.
def assign_position
return if position.present?
self.position = (user.assigned_tasks.maximum(:position) || 0) + 1
end
def stamp_completion
return unless completed_changed?
self.completed_at = completed? ? Time.current : nil
end
end
```
And the assignee side (plus a display-name fallback the views rely on):
```ruby
# app/models/user.rb (additions)
has_many :assigned_tasks, class_name: "Task", foreign_key: :user_id, dependent: :destroy
scope :team, -> { order(Arel.sql("full_name IS NULL, full_name ASC, email ASC")) }
def display_name
full_name.presence || email.split("@").first.titleize
end
```
## Layer 2 — Routes & Controllers
```ruby
# config/routes.rb
resources :team, only: [:index, :show], controller: "team" do
member { get :tasks } # /team/:id/tasks — one member's backlog
end
resources :tasks, only: [:create, :update, :destroy] do
collection { post :reorder } # persist drag-and-drop ordering
end
```
`TeamController` owns the read side. Tab and sort are **URL params, whitelisted to known
values** — the page state is shareable and back-button friendly, and no client state
machinery is needed:
```ruby
# app/controllers/team_controller.rb
class TeamController < ApplicationController
def index
@members = User.team.includes(:assigned_tasks)
end
# A member's task backlog. ?tab=completed switches lists;
# ?sort=priority orders high→low instead of the manual drag order.
def tasks
@member = User.find(params[:id])
@tab = params[:tab] == "completed" ? "completed" : "backlog"
@sort = params[:sort] == "priority" ? "priority" : "manual"
if @tab == "completed"
@tasks = @member.assigned_tasks.done
else
incomplete = @member.assigned_tasks.incomplete
@tasks = @sort == "priority" ? incomplete.by_priority : incomplete.manual_order
end
@open_count = @member.assigned_tasks.incomplete.count
@done_count = @member.assigned_tasks.done.count
end
end
```
`TasksController` owns the write side. Note `redirect_back` on update/destroy — it
preserves whatever `?tab=`/`?sort=` the user was viewing:
```ruby
# app/controllers/tasks_controller.rb
class TasksController < ApplicationController
before_action :set_task, only: %i[update destroy]
def create
@member = User.find(params.dig(:task, :user_id))
@task = @member.assigned_tasks.new(create_params)
@task.creator = current_user if respond_to?(:current_user) && current_user
@task.save
redirect_to tasks_team_path(@member)
end
def update
@task.update(update_params)
redirect_back fallback_location: tasks_team_path(@task.user)
end
def destroy
member = @task.user
@task.destroy
redirect_back fallback_location: tasks_team_path(member)
end
# POST /tasks/reorder — persist a drag-and-drop reordering.
# Body: { ids: [3, 1, 2] } top-to-bottom. Responds :ok for the JS fetch.
def reorder
Task.persist_order!(params[:ids])
head :ok
end
private
def set_task
@task = Task.find(params[:id])
end
def create_params
params.require(:task).permit(:description, :priority, :deadline, :details)
end
# The tickbox submits only :completed; the add form submits the rest.
def update_params
params.require(:task).permit(:description, :priority, :completed, :deadline, :details)
end
end
```
## Layer 3 — The Views
The directory (`/team`) — a card grid; each card carries a **Tasks** button with an
open-count badge:
```erb
<%# app/views/team/index.html.erb %>
<%= link_to tasks_team_path(member),
class: "inline-flex items-center gap-1.5 px-3 py-1.5 text-sm font-medium rounded-lg bg-slate-100 text-slate-700 hover:bg-indigo-50 hover:text-indigo-700 transition" do %>
Tasks
<% if open_tasks.positive? %>
<%= open_tasks %>
<% end %>
<% end %>
<% end %>
```
The backlog (`/team/:id/tasks`) — trimmed to the load-bearing parts; every UI state
(tab, sort) is just a link that sets a param:
```erb
<%# app/views/team/tasks.html.erb %>
<%# Drag handle — the ONLY grabbable zone (see Gotchas) %>
<% if draggable %>
<% end %>
<%# Tickbox: a one-field form that flips `completed` %>
<%= form_with model: task, class: "shrink-0 pt-0.5" do |f| %>
<%= f.hidden_field :completed, value: task.completed? ? "0" : "1" %>
<% end %>
<%# Description; native gives expand/collapse with zero JS %>
<% if task.details.present? %>
<%= task.description %>
<%= task.details %>
<% else %>
<%= task.description %>
<% end %>
<%= task.priority %>· Created <%= task.created_at.strftime("%b %-d, %Y") %>
<% if task.deadline.present? %>· Due <%= task.deadline.strftime("%b %-d, %Y") %><% end %>
<% if task.completed? && task.completed_at.present? %>· Completed <%= task.completed_at.strftime("%b %-d, %Y") %><% end %>
<%= @tab == "completed" ? "No completed tasks yet" : "No tasks in the backlog" %>
<% end %>
```
## Layer 4 — Stimulus + SortableJS
First, vendor SortableJS (Leo boxes have no npm and can't add gems). Download the ESM
build **into `app/javascript/`** (see Gotchas for why *not* `vendor/javascript/`):
```bash
# run inside the Rails container (docker compose exec llamapress bash)
curl -sL "https://ga.jspm.io/npm:sortablejs@1.15.6/modular/sortable.esm.js" \
-o app/javascript/sortablejs.js
```
Pin it:
```ruby
# config/importmap.rb (add this line)
pin "sortablejs", to: "sortablejs.js", preload: true
```
The Stimulus controller — SortableJS does the dragging; on drop we read the DOM's
current `data-task-id` order and POST it:
```javascript
// app/javascript/controllers/sortable_controller.js
import { Controller } from "@hotwired/stimulus"
import Sortable from "sortablejs"
// Drag-and-drop reordering for the task backlog.
// Usage on the
:
// data-controller="sortable"
// data-sortable-url-value="<%= reorder_tasks_path %>"
// Each
carries data-task-id. On drop we POST the new top-to-bottom id
// order so it persists across reloads.
export default class extends Controller {
static values = { url: String }
connect() {
this.sortable = Sortable.create(this.element, {
animation: 150,
handle: "[data-sortable-handle]",
ghostClass: "opacity-40",
onEnd: () => this.persist(),
})
}
disconnect() {
if (this.sortable) this.sortable.destroy()
}
persist() {
const ids = Array.from(this.element.querySelectorAll("[data-task-id]"))
.map((el) => el.dataset.taskId)
fetch(this.urlValue, {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-CSRF-Token": this.csrfToken,
},
body: JSON.stringify({ ids }),
})
}
get csrfToken() {
const meta = document.querySelector('meta[name="csrf-token"]')
return meta ? meta.content : ""
}
}
```
---
## Gotchas (the hard-won stuff)
- **Put the vendored `sortablejs.js` in `app/javascript/`, NOT `vendor/javascript/`.**
On Leo boxes `app/javascript` is part of the bind-mounted overlay and survives
container recreates and image updates; `vendor/` lives only inside the container, so a
file dropped there **silently vanishes on the next update/recreate** and every drag
interaction breaks with a 404 on the module. (The source project learned this the
fragile way.) The importmap resolves `to: "sortablejs.js"` from either location, so
the pin line is identical.
- **`config/importmap.rb` is a single-file bind mount — verify the edit landed in the
container.** Atomic-write editors swap the host file's inode and detach it from the
mount, so the running app keeps reading the old file and your pin silently no-ops.
After editing, check `docker compose exec -T llamapress grep sortable /rails/config/importmap.rb`;
if it's missing, rewrite in place:
`docker compose exec -T llamapress sh -c 'cat > /rails/config/importmap.rb' < rails/config/importmap.rb`.
- **Only offer dragging in Backlog + Manual mode** (`draggable = @tab == "backlog" && @sort == "manual"`).
Dragging while sorted by priority would persist an order the user isn't actually
seeing — confusing writes to `position` that only surface later in Manual mode.
- **Use a drag `handle`, not whole-card dragging.** The card contains a tickbox button,
a `` toggle, a delete button, and selectable text — whole-card drag hijacks
all of them. `handle: "[data-sortable-handle]"` scopes grabbing to the grip icon.
- **`position ASC NULLS LAST` everywhere you order by position.** Rows created before
the column existed (or via other code paths) have `NULL` positions; plain `ASC` puts
NULLs *first* in Postgres, shoving position-less rows to the top. If you add
`position` to an existing table, backfill per assignee:
`UPDATE tasks SET position = seq.rn FROM (SELECT id, ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY created_at) AS rn FROM tasks) seq WHERE tasks.id = seq.id`.
- **Scope `persist_order!` writes to ids you actually own.** The method plucks the ids
that exist within `scope` and ignores the rest, so a tampered POST body can't renumber
another member's (or another tenant's) rows. If you have auth, tighten the call site:
`Task.persist_order!(params[:ids], scope: current_user.visible_tasks)`.
- **The tickbox is a form, not JS.** `f.hidden_field :completed, value: task.completed? ? "0" : "1"`
plus a submit button = toggle with zero JavaScript, and `redirect_back` keeps the user
on their current tab/sort. `stamp_completion` sets/clears `completed_at` in one place
(the model), so the "Completed" list can order by it reliably.
- **The reorder endpoint must return `head :ok`.** The Stimulus `fetch` expects a bare
2xx; rendering a redirect there makes fetch follow it and pointlessly render HTML.
Also note the CSRF token header — without `X-CSRF-Token` Rails rejects the POST with
a 422 (`InvalidAuthenticityToken`).
- **Raw SQL fragments in `order` need `Arel.sql(...)`** (`NULLS LAST`, the priority
`CASE`). Passing the string directly raises Rails' unsafe-SQL error.
- **Priority sort ranks in SQL, not Ruby.** The `CASE priority WHEN 'high' THEN 0 …`
scope keeps ordering in the database (composable with pagination/limits) instead of
loading and sorting in memory.
- **Font Awesome icons** (`fa-grip-vertical`, `fa-check`, `fa-trash`, `fa-chevron-right`)
are used throughout — available on most Leo boxes but not guaranteed. Unicode
fallbacks work fine: `⋮⋮` for the grip, `✓` for the check, `▸` for the chevron.
- **`/` gives expandable notes for free** — no Stimulus, works inside
the draggable list, and `group-open:rotate-90` on the chevron is pure Tailwind.
---
## Files this pattern touches
```
db/migrate/XXXX_create_tasks.rb
app/models/task.rb
app/models/user.rb (association + team scope)
app/controllers/team_controller.rb
app/controllers/tasks_controller.rb
app/views/team/index.html.erb
app/views/team/tasks.html.erb
app/javascript/controllers/sortable_controller.js
app/javascript/sortablejs.js (vendored ESM build)
config/importmap.rb (one pin line)
config/routes.rb
```
## How to adapt to your schema
1. **Different parent than User:** the pattern is parent-has-ordered-checkable-children.
Swap `user_id` for `project_id`/`client_id`/etc., rename `assigned_tasks`, and change
the nested route (`resources :projects do member { get :tasks } end`). Everything
else is mechanical.
2. **No manual ordering needed?** Drop `position`, `persist_order!`, the reorder route,
the Stimulus controller, and the SortableJS vendoring — you lose one file of JS and
the whole feature still works with priority/created-at ordering.
3. **No deadline/details?** Drop those two columns and their form fields/card fragments;
the migration, tickbox, tabs, and sort are independent of them.
4. **More priorities or statuses:** extend `PRIORITIES` and the `CASE` scope together
(they must agree), and add a dot color to the view's `dot` map.
5. **Auth:** the source app ran with open auth. With Devise, set
`@task.creator = current_user` unconditionally, add `authenticate_user!`, and scope
`persist_order!` as shown in Gotchas.
6. **The sortable Stimulus controller is reusable as-is** for any list — it only needs
`data-task-id` on children and a URL that accepts `{ ids: [...] }`.