Integrations

This document defines the target API and integration architecture for the Headkount build phase.

The design connects Headkount with workforce systems, retailer portals, communication tools, and source files. Postgres remains the main Headkount record.

This section defines the build target. It does not claim that every connector is live today.

Integration definitions

Integration	Business definition
Connecteam	Provides beauty educator profiles, eligibility, availability, Time Off, existing shifts, and published schedules.
Slack	Provides messages and files that explain Brand requirements, Door changes, Events, and operating decisions.
Source file importer	Brings approved trackers, contracts, Brand files, and retailer directories into Headkount.
Sephora provider	Reads live availability and booking state. It also submits approved bookings.
Ulta provider	Reads Event state and submits approved Event requests. Regular Ulta visits do not require portal availability.
Confirmation mailbox	Provides supporting evidence for retailer confirmations. The retailer portal remains the owner of current booking state.
Headkount command API	Accepts approved actions from the interface, AI Agent, and integration workers.
Electric Sync	Sends committed Postgres changes to authorized application views.

System map

Connecteam ----\
Slack ----------\
Source files ----> Inbound connectors -> Bronze -> Silver -> Postgres
Sephora --------/                              |          |
Ulta ----------/                               |          v
                                                |     Electric Sync
                                                |          |
                                                |          v
                                                |   Headkount interface
                                                |
Approved action -> Command API -> Work queue ---+
                                     |
                                     v
                              Connector worker
                                     |
                                     v
                              External system
                                     |
                                read result back
                                     |
                                     v
                                  Postgres

Inbound connectors copy external information into Headkount. Outbound workers act only on approved commands.

External connector plan

Integration	Direction	Access	Operating pattern
Connecteam	Inbound and outbound	Connecteam API key	Read on a schedule. Reconcile the full source periodically. Create draft shifts after confirmed bookings.
Slack	Inbound only	Bot token and signed events	Receive new events. Backfill approved channels. Reconcile missed changes on a schedule.
Source files	Inbound only	Authorized User upload	Import each approved file version. Keep the original file and its import history.
Sephora	Inbound and outbound	Per-Brand bearer link in an authorized browser session	Read availability and bookings. Submit approved bookings. Re-read every result.
Ulta	Inbound and outbound	Per-Brand credentials in an authorized browser session	Read Event status. Submit approved Event requests. Re-read every result.
Confirmation mailbox	Inbound only	Authorized mailbox access	Read confirmation messages and link them to the related retailer booking.

The existing Connecteam and Slack readers provide the starting point. The build adds approved outbound commands and retailer providers.

Retailer provider contract

Each retailer provider supports the same business operations.

Operation	Business purpose	Rule
Start session	Opens authorized access for one retailer and Brand.	Credentials come from the secret manager.
Read availability	Returns the bookable Doors, dates, and times.	If the retailer provides availability, the operation runs.
Read bookings	Returns current requests, approvals, denials, cancellations, and reschedules.	The retailer remains the owner of this state.
Submit booking	Sends one approved visit or Event request.	The worker records the attempt before it sends the request.
Confirm result	Reads the retailer state after a submission.	A submission response alone does not prove confirmation.
Report health	Reports access, source freshness, and connector errors.	A failed health check stops outbound actions for that source.

Sephora uses a real browser session with structured GraphQL requests. The provider reads live slots before it submits an approved booking.

Ulta uses a real browser session with structured REST requests. The provider manages per-Brand credentials and the Event workflow.

Retailer-specific details stay inside each provider. The rest of Headkount uses one shared booking model.

The system does not automate retailer cancellations. Staff complete cancellations through the retailer workflow and record the result in Headkount.

Shared data contracts

Each connector converts external information into a shared Headkount record.

Record	Business identity
Beauty educator	External person, employment state, Market, and eligible Brands and Doors
Blocked time or shift	External record, beauty educator, start, end, timezone, and status
Door reference	Retailer, store number, address, Market, and source identifier
Portal slot	Retailer, Brand, Door, visit type, local time, status, and observation time
Retailer booking	Schedule Assignment, retailer reference, requested time, and current result
Connecteam shift	Schedule Assignment, Connecteam reference, time, and publication state
Message or file evidence	Source, external identifier, time, author, content, and protected file reference

Every external record keeps its source identifier. When connectors link records, they use stable identifiers instead of names and free text.

Retailer-specific fields remain in the source evidence. The application adds these fields to a business record only for a business need.

Inbound flow

External source
      |
      v
Exact source evidence       Bronze
      |
      v
Standardized record         Silver
      |
      +----> Integration Issue when data is invalid or unmatched
      |
      v
Trusted Headkount record    Postgres
      |
      v
Live application view       Electric Sync

The connector saves the source evidence before it changes the data format. A repeated import does not create duplicate business records.

If the importer cannot match a person, Brand, Door, or booking, it does not guess. It creates an Integration Issue for staff review.

Outbound flow

Approved Schedule Assignment
            |
            v
      Typed command
            |
            v
   Recorded action attempt
            |
            v
     Retailer provider
            |
            v
    Read-back confirmation
            |
            v
Confirmed Retailer Booking
            |
            v
   Draft Connecteam Shift

Each outbound action has one stable action key. A retry cannot create a second booking or shift.

The worker reads the external source before it retries an unclear result. Only the read-back result changes the booking to confirmed.

Source ownership

Information	Owner
Beauty educator profiles and eligibility after migration	Headkount application
Existing shifts and Time Off	Connecteam
Slack messages and files	Slack
Historical tracker and directory evidence	The imported source file
Portal availability and booking state	The retailer portal
New Contracts, required work, Schedules, and approvals	Headkount application

A connector updates only the information that its source owns. A source conflict creates an Integration Issue.

Failure and fallback

Condition	System response	Business fallback
A source is unavailable	Keep the last trusted data and mark the source as stale.	Staff use the external system directly.
A credential expires	Pause that connector and show a credential alert.	Staff use the manual process until access returns.
An external data format changes	Reject the new data and preserve the prior trusted record.	Staff use the external system while the provider is updated.
A record cannot match	Keep the record outside the main data and create an Integration Issue.	Staff select or create the correct Headkount record.
A write result is unclear	Read the external state before any retry.	Staff read and record the result in the external system.
Portal automation is unavailable	Stop automated portal actions.	Staff complete the approved booking manually and record the result.
Connecteam is unavailable	Keep the confirmed retailer booking.	Staff create the draft shift manually. The next sync reconciles it.

The manual process remains available for every external action. Automation does not remove direct access to Connecteam or retailer portals.

Security and control

• Credentials stay in a protected secret manager. Database records contain secret references only.
• Each connector receives only the access that it needs.
• External writes require an approved command and a complete audit record.
• The worker records every attempt before it contacts an external system.
• Logs and source evidence do not contain passwords, tokens, or bearer links.
• Automation uses authorized sessions at a controlled rate.
• Automation does not bypass access limits, CAPTCHA controls, or retailer restrictions.
• Staff can stop one connector without stopping the Headkount application.

Application interfaces

The interface and AI Agent send writes through typed oRPC commands. Effect validates the User, role, input, approval, and business rules.

Postgres commits each command as one transaction. Electric Sync then sends the committed result to authorized browser views.

The browser never selects arbitrary database tables. Server-owned Electric shapes define the approved records, fields, filters, and access rules.

Hosting and repository fit

Vercel hosts the Headkount web application. AWS hosts Postgres, Electric Sync, ingestion jobs, and retailer portal workers.

Protected source files and connector evidence use Amazon S3. External systems remain outside the Headkount hosting boundary.

The build keeps the current systems/connecteam and systems/slack boundaries. It adds one systems/retailer-portal boundary with a provider for each retailer.

Applications compose workers and routes. Database migrations remain in packages/database.

Result

This architecture gives Headkount one controlled path for imports, live updates, approved external actions, confirmation, error recovery, and manual fallback.