Implementation Details

This page covers what was built, the stack choices, assumptions, known limitations, and the rough build sequence.

Repository: github.com/codebyshennan/d2c-rostering

What Was Built

The product centres on the roster operating loop: an admin creates shifts, invites or directly assigns ambassadors, staff accept or decline, and operations sees computed coverage plus a prioritised action queue. Field staff have a mobile path to review invitations, open directions, manage availability, check in with GPS, and submit a short post-shift report. Those reports feed client rollups and CSV exports.

The app also includes campaign, store, staff, equipment, route, payroll, notification, and integration surfaces around that loop.

Objective Coverage

The objective was to design and build a rostering tool that helps D2C manage field staff shifts for campaign work. The MVP covers that through a live roster spine: campaigns, stores, staff, shifts, assignments, responses, check-ins, reports, equipment, and notifications.

The admin side supports creating and managing shifts across dates, times, campaigns, locations, states, retailers, stores, formats, staff needs, required skills, and equipment. Admin users can invite staff, directly assign known ambassadors, review response status, see coverage and action queues, inspect shift detail, add briefing files, review field reports, maintain supporting records, export data, and use route, payroll, notification, integration, and setup surfaces.

The staff side supports the basic field workflow: staff can sign in, see invitations, accept or decline shifts, review confirmed work, open directions, see briefing files and equipment context, manage availability, check in with a one-time geolocation fix, and submit reports after completed shifts.

The product answers the practical operating questions in the brief:

What shifts are coming up: the admin overview, filters, calendar/list views, campaign pages, staff portal, and calendar feed expose upcoming work.
Who is needed for each shift: each shift stores staff needed, format, required skills, equipment, campaign, store, and timing.
Which staff have been invited or assigned: shift detail separates invited, confirmed, and declined assignments.
Who has accepted, declined, or not responded: assignment status is tracked directly and summarised in coverage/action views.
What operations needs to action next: the action queue and shift coverage buckets surface at-risk work, pending replies, open slots, and follow-up actions.
What field staff need to see or do: the staff portal shows pending invitations, confirmed shifts, directions, briefing links, check-in, availability, and reporting.

The minimum MVP expectations are covered: shifts are represented as structured records, staff are connected through assignments, shift status is tracked through assignment responses and computed coverage, admins can understand the roster from overview/detail views, and staff can interact with a shift from the mobile portal.

I used a real database rather than only mock data because the core product value depends on relational state changing over time: invite, accept, decline, check in, report, export, and aggregate. Seed data still exists so review and test environments have realistic campaign scenarios without needing live D2C data.

This is not presented as production-complete. The implementation is deliberately scoped to show product thinking, code quality, UX judgement, communication, speed of execution, and technical ownership while keeping larger ERP, CRM, award-aware payroll, advanced optimisation, and production notification setup as follow-on work.

Stack and Why

The app is a full-stack Next.js App Router application with TypeScript and Server Actions. That keeps the admin UI, staff UI, and mutations in one deployable repo.

Postgres is the centre of gravity because the domain is relational: campaigns, stores, shifts, assignments, staff responses, check-ins, reports, equipment, and notifications. Prisma 7 sits on Neon Postgres using the Rust-free generated client and Neon serverless driver adapter.

Coverage, action queue status, payroll totals, route distance, and candidate ranking are computed in code rather than stored as opaque fields. That keeps the roster truth explainable and testable.

Rostering Intelligence

The current rostering logic is intentionally explainable. It is not an opaque auto-scheduler. The product should help operations make a faster staffing decision, while still showing why that decision is being suggested. Candidate ranking looks at practical operating signals: required skills, home state, availability, existing assignments, staff coordinates, store coordinates, and distance where both sides are geocoded. A missing required skill is treated as a hard warning, while distance, state fit, availability, and double-booking risk are presented as reasons and warnings for the operator to review.

The action queue uses the same philosophy. It highlights exposed shifts, open slots, pending replies, missing check-ins, missing reports, and other next actions so operations can decide what to do. Route views group confirmed work by staff member and day, then show stops in time order with great-circle distance where coordinates exist. Payroll estimates multiply completed confirmed shift hours by the staff member's stored hourly rate. These are decision-support tools, not final optimisation, payroll, or compliance engines.

That posture matters for D2C because the useful intelligence is often operational rather than purely mathematical. A better future version could learn which ambassadors reliably accept certain campaigns, which stores need more experienced staff, which routes are unrealistic, which equipment is commonly missed, which reports are late, and which campaign formats create the most follow-up. Those signals should still stay explainable: show why a person, route, or action is recommended, then let operations override with a recorded reason.

Eligibility first

Required skills, clashes, and availability warnings come before optimisation. The app should avoid recommending someone who cannot realistically do the shift.

Distance as signal

Distance helps rank nearby ambassadors and flag unrealistic routes, but it should stay a review signal until staff and store coordinates are trusted.

Human review

Operations should see reason chips, warning chips, and fallback context before inviting, assigning, nudging, or overriding a suggestion.

Learn from outcomes

Accepted invites, declines, late reports, check-ins, route strain, and equipment misses can become future signals once the operating data is clean.

Current Decision Rules

The MVP intelligence works as a set of transparent rules:

Candidate fit: required skills act as the strongest gate; staff skills, home state, coordinates, availability, and existing assignments explain the rank.
Nearby staff: the same coordinate signal powers the "Who's nearby" map and distance-aware invitation flow, so operators can find close ambassadors before selectively inviting or assigning.
Action queue: exposed shifts, open slots, pending replies, missed check-ins, and missing reports are treated as operations work, not passive analytics.
Route view: confirmed work is grouped by ambassador and day so operations can inspect same-day movement, stop order, and distance warnings.
Payroll estimate: completed confirmed shifts generate an estimate from worked hours and stored hourly rates, but finance review still owns final payroll.

Future Intelligence Worth Building

The next intelligence layer should improve confidence, not remove operator judgement. D2C could add acceptance likelihood, staff reliability, campaign-fit scoring, equipment-risk prompts, travel-time warnings, report-quality checks, and store complexity signals. Those features become useful only when the underlying records are clean enough: staff identity, store coordinates, campaign types, equipment needs, report quality, and historical acceptance data.

The product should keep four guardrails around that future intelligence: show the reason, show the missing data, allow override, and record the decision. That makes the tool useful during piecemeal migration from D2C's existing tools because recommendations can improve gradually without forcing operations to trust a hidden model too early.

Assumptions

The build prioritises the roster truth before deeper ERP, CRM, finance, or HR scope. The main assumed roles are operations/admin users and field staff users. Demo data is intentionally realistic enough to exercise campaign, state, store, staff, shift, equipment, report, check-in, and notification flows.

Where the brief left product decisions open, the app keeps status visible and reversible rather than hiding uncertainty in automation. Candidate ranking shows reasons and warnings, notifications are recorded in an outbox, and setup/integration gaps are surfaced instead of treated as complete. Existing D2C tools, ERP, CRM, finance workflows, and reporting dashboards should be integrated gradually after source-of-truth ownership is known.

Known Limitations

Recurring availability is still a pragmatic MVP representation; production recurrence should use explicit wall-clock rules.
Candidate ranking and action queue scoring are transparent heuristics, not tuned optimisation models.
Notification delivery depends on provider and sender configuration; the outbox still records skipped or failed delivery.
GPS check-in captures one point-in-time fix, not continuous tracking, check-out, or geofencing.
Route planning is time-ordered with straight-line distance, not full travel-time optimisation.
Payroll is an hours-times-rate estimate, not award-aware finance logic.
The JSON export is a handoff/export surface, not a live two-way ERP or CRM API.
Existing D2C tools still need discovery before deciding whether to keep, wrap, migrate, rebuild, or retire them.

Rough Timelog

Area	Approx
Scaffold, database setup, empty deploy	0.5 h
Schema and seed data	1 h
Coverage and action queue logic	1 h
Admin workflow	2.5 h
Field staff workflow	1 h
Routes, payroll, reports, notifications, and integrations	2 h
Polish, docs, deployment verification	1 h

Verification

The project uses TypeScript, Vitest, and Playwright. The main CI path runs typecheck, unit tests, build, migrations against the configured database, and end-to-end coverage for the core admin and staff flows.