Project: a task tracker, end to end

Part IV explained the pieces. This chapter uses them, in order, to build something a small team could actually run: projects, tasks with a status and an assignee, comments, a dashboard, and a web page that is not the admin panel.

Everything here is a command you type and a file you open. Nothing is skipped for space, and the parts that are genuinely tedious are called tedious rather than hidden.

What we are building

A tracker with three models and one rule that matters:

• Project
• A name, a colour, an owner. Archived rather than deleted
• Task
• Belongs to a project, has a status, an assignee and a due date
• Comment
• Belongs to a task, written by a user

The rule: a task cannot be closed while it has open subtasks, which is the kind of thing that is trivial to state, easy to enforce in one place, and impossible to enforce if it lives in a form.

Step one: the project

grit new tracker
cd tracker
grit start

Three applications come up: the API on :8080, the web app on :3000 and the admin on :3001. Log in with the seeded admin account printed in the output, and confirm the dashboard renders before generating anything. A broken starting point is worth five minutes to rule out.

Step two: the resources

Generate the parent first, because the child refers to it:

grit generate resource Project \
  --fields "name:string, colour:color, archived:bool" \
  --owned-by user

Then the task, with the relationship and a real status:

grit generate resource Task --fields "\
title:string, \
notes:richtext, \
status:select:todo=To do|doing=In progress|done=Done, \
priority:select:low=Low|normal=Normal|high=High, \
due:date, \
project:belongs_to:Project, \
assignee:belongs_to:User"

And the comment:

grit generate resource Comment \
  --fields "body:text, task:belongs_to:Task"

Then once:

grit migrate

Reload the admin. Three new sections in the sidebar, each with a working list and form. The task form has two dropdowns with labels rather than raw values, a date picker, a rich text editor, and two searchable relationship pickers.

Step three: the rule, in the only place it can live

Open apps/api/internal/services/task.go and add a method. This is chapter thirty two, applied:

var ErrHasOpenSubtasks = errors.New(
    "task has open subtasks")

func (s *TaskService) Close(ctx context.Context, id uint) (
    *models.Task, error) {

    task, err := s.GetByID(ctx, id)
    if err != nil {
        return nil, err
    }

    var open int64
    if err := s.db(ctx).Model(&models.Task{}).
        Where("parent_id = ? AND status != ?", id, "done").
        Count(&open).Error; err != nil {
        return nil, fmt.Errorf("counting subtasks: %w", err)
    }
    if open > 0 {
        return nil, ErrHasOpenSubtasks
    }

    task.Status = "done"
    if err := s.db(ctx).Save(task).Error; err != nil {
        return nil, fmt.Errorf("closing task %d: %w", id, err)
    }
    return task, nil
}

The subtask relationship needs a column, which is one command rather than a migration file:

grit generate field Task parent:belongs_to:Task
grit migrate

A self-referencing belongs_to is legal and useful: it is how a task gets subtasks without a second model.

Step four: the endpoint

func (h *TaskHandler) Close(c *gin.Context) {
    id, err := strconv.ParseUint(c.Param("id"), 10, 64)
    if err != nil {
        respond.BadRequest(c, "invalid id")
        return
    }

    task, err := h.service().Close(h.ctx(c), uint(id))
    if err != nil {
        respond.Fail(c, err)
        return
    }
    respond.OK(c, task)
}

Register it next to the generated routes:

tasks.POST("/:id/close", h.Task.Close)

And teach the boundary what the new error means, so the frontend gets a 409 rather than a 500:

case errors.Is(err, services.ErrHasOpenSubtasks):
    respond.Conflict(c, err)

Check it is wired:

grit routes

That prints every registered route with its method, handler and middleware group, which is the fastest way to catch a route registered on the wrong group and therefore unauthenticated.

Step five: data worth looking at

An empty application tells you nothing about whether it works:

grit seed Project --count 8
grit seed Task --count 400
grit seed Comment --count 1200

Four hundred tasks is where the list page stops being a demo. Sort by due date, filter by status, search a title, and page through. Pagination is server side, so the browser is holding twenty rows no matter how many exist.

Step six: the admin screen, customised

The generated list is correct and plain. Two changes make it usable, and both live in apps/admin/app/_dashboard/resources/task/index.tsx.

A status badge rather than a word:

{
  key: "status",
  label: "Status",
  sortable: true,
  render: (row) => {
    const tone = {
      todo:  "bg-slate-500/15 text-slate-300",
      doing: "bg-amber-500/15 text-amber-400",
      done:  "bg-emerald-500/15 text-emerald-400",
    }[row.status]
    return <span className={`rounded px-2 py-0.5 ${tone}`}>
      {row.status}</span>
  },
}

And an overdue due date, because a date that is late should look late:

{
  key: "due",
  label: "Due",
  sortable: true,
  render: (row) => {
    const late = row.status !== "done" &&
      new Date(row.due) < new Date()
    return <span className={late ? "text-red-400" : ""}>
      {formatDate(row.due)}</span>
  },
}

Re-run the generator for Task afterwards and confirm these survive. They are in the file the generator writes once.

Step seven: a page the admin cannot be

An operator console is not a product. The team wants a board, so write one as an ordinary Next.js page using the generated hooks:

export default function BoardPage() {
  const { data, isLoading } = useTasks({ page_size: 200 })
  if (isLoading) return <BoardSkeleton />

  const columns = ["todo", "doing", "done"] as const
  return (
    <div className="grid gap-4 md:grid-cols-3">
      {columns.map((status) => (
        <Column
          key={status}
          title={LABELS[status]}
          tasks={data.data.filter((t) => t.status === status)}
        />
      ))}
    </div>
  )
}

Moving a card calls the same API the admin does:

const { mutate } = useUpdateTask()
mutate({ id: task.id, status: "doing" })

Nothing here is framework-specific. It is React against typed hooks, and the types came from the Go model through chapter thirty six's shared package, so renaming due in the model makes this page fail to compile rather than fail in front of a user.

Step eight: a form for people without accounts

Bug reports should not require an admin login. One command writes the page:

grit expose form Task --to apps/web/app/report/page.tsx

That emits a Next.js page with one input per field, submitting through the authenticated create hook. For a genuinely public form, create a form share in the admin under System, then:

grit expose form Task --to apps/web/app/report/page.tsx \
  --public-share --token 9CkLh7gJZ...

which posts to the public submission endpoint instead, with no account required.

Step nine: the things that make it a product

Four small commands, each closing something a client will ask about:

grit add role MANAGER
grit backup
grit doctor
grit routes

A role that the sidebar, the forms and the seeded permissions all know about. A backup you have actually taken. A health check across the project. A route list you have read, looking for anything registered outside the authenticated group.

What it cost

Count honestly, including the parts nobody counts:

• Three resources, migrated, in the admin
• four commands
• The business rule and its endpoint
• about 40 lines
• Two customised columns
• about 25 lines
• The board page
• about 80 lines
• Everything else: auth, lists, forms, validation, types, hooks
• generated

Compare that with chapter forty eight, where one resource with no admin panel and no frontend took about six hundred lines. That ratio is the entire argument of this book, and now you have both numbers from your own machine rather than from a marketing page.

Assignment

Commit your work with the message Task Tracker - Assignment One, exactly as written, so the leaderboard can score it.