Implementation Plan

This document defines the recommended plan for the Headkount Build and Launch phase.

The estimated delivery period is 12 weeks. The schedule starts after contract signature, kickoff payment, and required access.

Build target

The Build phase will deliver one production application for scheduling and daily operations.

Users
  |
  v
Next.js application on Vercel
  |
  +----> Typed commands through oRPC and Effect
  |
  v
Postgres on AWS RDS
  |
  +----> Electric Sync ----> TanStack DB ----> Live interface
  |
  +----> Schedule Optimizer
  |
  +----> Ingestion and retailer workers on AWS
  |
  +----> Activity history and observability

Technology

Area	Technology	Purpose
Web application	Next.js, React, and Tailwind CSS	Provides the Headkount interface.
Web hosting	Vercel	Builds and serves the web application.
Database	AWS RDS Postgres and Drizzle	Stores all durable application records.
Live data	Electric Sync and TanStack DB	Sends committed records to the interface.
Commands	oRPC and Effect	Validates access, input, errors, and business rules.
Authentication	Better Auth	Manages accounts, sessions, invitations, and roles.
Schedule generation	Deterministic TypeScript Optimizer	Creates Schedule Versions from approved inputs and rules.
AI Agent	AI SDK and typed tools	Reads records and prepares approved commands.
Background work	AWS workers	Runs imports, portal providers, reconciliation, and alerts.
Files	Amazon S3	Stores protected imports and source evidence.
Monitoring	OpenTelemetry, Loki, Tempo, and Grafana	Connects logs and traces to Users, commands, and workers.

Environments

Environment	Purpose	External access
Local	Development with an isolated Postgres and Electric stack	Local test data only
Staging	Acceptance, migration rehearsal, portal reads, and dry-run actions	Read-only or approved test access
Production	Live Headkount operations	Approved production access

Staging and Production use separate databases, credentials, storage, and worker queues.

Delivery phases

Phase 1: Foundation and migration tools

Weeks 1–2

• Create the production and staging environments.
• Finish the canonical database schema and migrations.
• Configure authentication, roles, secrets, logs, and backups.
• Build repeatable import tools for the current database and source files.
• Load a reviewed staging data set.

Result: Headkount can sign in to staging and review the migrated business records.

Phase 2: Core records and Schedule

Weeks 3–5

• Finish Users, Beauty Educators, Brands, Markets, Retailers, and Doors.
• Finish Contracts, commitments, and required work.
• Finish the Month, Week, and Day calendar.
• Add the Market, Beauty Educator, Brand, and Door filters.
• Add Schedule generation, versions, gaps, warnings, and approval.

Result: A Scheduler can generate, review, filter, and approve a complete Schedule Version.

Phase 3: Integrations and daily operations

Weeks 6–8

• Finish Connecteam and Slack ingestion.
• Finish file imports and source-health views.
• Build the shared retailer-provider system.
• Build Sephora reads, dry-run booking, confirmation, and manual fallback.
• Build the Ulta Event adapter under the same provider boundary.
• Add bookings, draft Connecteam shifts, tickets, and activity history.

Result: Staging shows the full path from source data to booking confirmation and draft shift.

Phase 4: AI Agent and launch candidate

Weeks 9–10

• Add the Agent to the Schedule and business record screens.
• Add read tools and approval-gated write tools.
• Add Schedule Instructions and generation requests.
• Add undo commands, activity history, and permission tests.
• Complete the production launch candidate.

Result: A User can ask for a change, review the proposal, approve it, and see the committed result.

Phase 5: Pilot and launch

Weeks 11–12

• Rehearse the final data migration.
• Complete User acceptance testing with Headkount.
• Train Admins and Schedulers.
• Run a controlled production pilot.
• Reconcile Schedule, portal, and Connecteam results.
• Move the approved application to production.

Result: Headkount operates the approved production system with monitoring and manual fallback.

Data migration

The migration uses the same repeatable process for every source.

1. Save a read-only source copy.
2. Standardize identifiers, names, dates, times, and status values.
3. Link source records to the canonical Headkount records.
4. Load valid records into staging.
5. Compare source counts, required work, scheduled work, and unmatched records.
6. Rehearse the production migration.
7. Pause legacy changes during the final cutover window.
8. Apply the final migration and repeat the reconciliation.

The legacy sources remain available as evidence. The production application uses the canonical records after cutover.

Testing

Test	Purpose
Unit tests	Prove business rules, calculations, and state changes.
Contract tests	Prove each external response matches the expected data contract.
Database tests	Prove constraints, migrations, transactions, and duplicate protection.
Integration tests	Prove complete flows across the application, database, and workers.
Browser tests	Prove the main User workflows in supported browsers.
Security tests	Prove roles, sessions, secret handling, and restricted data access.
Migration tests	Prove source counts, mappings, totals, and repeatability.
Failure tests	Prove retries, stale-source behavior, alerts, recovery, and manual fallback.
User acceptance tests	Prove that Headkount can complete the agreed operating workflows.

Each external write starts in dry-run mode. Production writes begin only after a reviewed staging result and explicit approval.

Deployment

1. Build and test one immutable release candidate.
2. Deploy the candidate to Staging.
3. Complete automated tests and User acceptance tests.
4. Review the database migration and infrastructure changes.
5. Apply the approved production migration.
6. Deploy the same tested application version to Production.
7. Complete sign-in, data, schedule, integration, and monitoring checks.
8. Keep the prior application and manual workflows available during the pilot.

A failed release check stops the launch. The team corrects the release in Staging before another production attempt.

Launch criteria

• Authorized Users can sign in with the correct roles.
• Migrated record counts and work totals match the approved reconciliation report.
• The Schedule shows the expected Month, Week, and Day data.
• The four calendar filters return the correct cards.
• The Optimizer produces repeatable Schedule Versions.
• Every write records the User, reason, and activity history.
• Connecteam, Slack, files, and retailer connectors report their health.
• Retailer actions require approval and read-back confirmation.
• The AI Agent cannot bypass approval or application rules.
• Backups, logs, traces, alerts, and recovery steps operate in Production.
• Headkount accepts the pilot results.

Dependencies

• Headkount provides one project owner with decision authority.
• Headkount provides authorized access to source systems and retailer portals.
• Headkount provides the final source files and approved business records.
• Headkount reviews milestone results within two business days.
• Thinair receives access to the required AWS, Vercel, DNS, and email accounts.
• Retailer writes remain off until Headkount gives explicit production approval.

An access or review delay moves the delivery dates by the same amount. A scope change uses the change process in the MSA.

Main risks and controls

Risk	Control
Source records conflict	Keep source evidence and route the conflict to a User.
A retailer changes its portal	Stop the provider, alert the team, and use the manual workflow.
A credential expires	Pause that connector and show a credential alert.
A booking result is unclear	Read the retailer state before any retry.
The Optimizer leaves work unfilled	Show each gap and its reason before approval.
The Agent proposes an invalid action	Reject it through deterministic command rules.
A migration produces different totals	Stop cutover and return to the prior application.
A production service stops	Alert the team and use the documented recovery process.

Result

This plan delivers the full system in five controlled phases, with acceptance evidence at the end of each phase.