Domain Model

This page explains how Flowstate's core entities relate to each other. Understanding this model will help you build integrations that correctly manage employees, track costs, and keep your workforce data in sync.

Entity Relationship Diagram

Reading this diagram

Solid arrows show data relationships. Dotted arrows show references to configuration entities. Assignments are the central link — they connect any resource (Employee, Contractor, Vacancy) to any target (Team or Project) with an FTE value and date range.

---

Core Entities

Employees, Contractors, and Vacancies

These are the three types of resources in Flowstate -- the people (or planned people) that make up your workforce.

Entity	What it represents	Key difference
Employee	A person employed by your organization (full-time or part-time).	Has a salary history via Salary Adjustments.
Contractor	An external individual or firm engaged on a contract basis.	Has a rate history via Rate Adjustments. Rates can be hourly, daily, or monthly.
Vacancy	A planned hire that has not yet been filled.	Can be converted into an Employee via the Fill endpoint.

All three resource types can be assigned to teams and projects using the same Assignments model.

Teams

Teams represent organizational units (e.g. "Platform Engineering", "Growth Squad"). Teams form a hierarchy through parentTeamId -- a team with no parent is a top-level department.

Teams are the primary organizational structure. Employees and contractors are assigned to teams, and teams can be allocated to projects.

Projects

Projects represent work initiatives with timelines and budgets. People and teams are allocated to projects using Assignments. Each project can have a lifecycle stage, a value stream, and cost estimates.

---

Temporal Records: Why Salary and Rate Adjustments Are Separate

Flowstate tracks compensation as a series of point-in-time records, not as a single mutable field.

Salary Adjustments (Employees)

Each salary adjustment has an effectiveDate, salary, bonus, and currencyCode. The most recent adjustment by date is the employee's current salary.

Employee: Jane Chen
  2024-03-15  Starting salary:    GBP 85,000
  2025-04-01  Annual review:      GBP 90,000
  2026-01-01  Promotion:          GBP 105,000  <-- current salary

Why this matters for integrations:

• Creating a new salary adjustment does not modify or delete previous ones.
• To change an employee's salary, create a new adjustment with a future effectiveDate.
• To correct a mistake, update the specific adjustment record.
• Flowstate uses the full history for cost forecasting and variance analysis.

Rate Adjustments (Contractors)

The same temporal model applies to contractors. Each rate adjustment has effectiveDate, rateType, rate, and currencyCode. The most recent adjustment is the current rate.

---

Assignments: Date-Bounded Allocations

Assignments are the connections between resources (employees, contractors, vacancies) and targets (teams, projects). Each assignment has:

• FTE -- how much of the resource's capacity is allocated (e.g. 0.5 = half-time)
• startDate / endDate -- when the allocation is active

An employee can have multiple concurrent assignments (e.g. 0.6 FTE on Team A and 0.4 FTE on Team B). Assignments are independent records -- creating a new one does not end existing ones.

Request vs. Response schema

When creating an assignment, you provide teamId or projectId to specify the target. In the response, the API returns type ("team" or "project") and targetId. See the Assignments reference for details.

---

The Vacancy Fill Workflow

Vacancies represent planned hires. When a candidate is hired, you "fill" the vacancy to convert it into an employee:

1. Create a Vacancy with role, salary range, and team assignments
2. (Recruitment happens outside Flowstate)
3. POST /vacancies/:id/fill with the new hire's details
4. Flowstate atomically:
   a. Creates a new Employee
   b. Creates an initial Salary Adjustment
   c. Copies all vacancy assignments to the new employee
   d. Marks the vacancy as "filled"

This ensures that headcount forecasting seamlessly transitions from planned (vacancy) to actual (employee) without gaps in the data.

See the Vacancies: Fill endpoint and the Recipes: Fill a Vacancy guide.

---

Cost Calculation Chain

For integration partners building financial reports, here is how Flowstate derives costs:

Employee Cost = Salary + Bonus + (Salary x Work Type Overhead %) x Location Cost Multiplier
                        |
                        v
          Exchange Rate converts to reporting currency
                        |
                        v
      Assignment FTE distributes cost across teams/projects

1. Base compensation: From the most recent Salary Adjustment (employees) or Rate Adjustment (contractors).
2. Overhead: The employee's Work Type defines an overheadPercentage (e.g. 30%) applied to salary.
3. Location multiplier: The Location's costMultiplier adjusts for geographic cost differences.
4. Currency conversion: Exchange Rates convert local currency to the organization's reporting currency.
5. Distribution: Assignment FTE values determine how much of each person's cost is attributed to each team or project.

---

Configuration Entities

These entities are shared reference data used across the system:

Entity	Purpose	Used by
Locations	Geographic locations with currency defaults and cost multipliers.	Employees, Contractors, Vacancies
Work Types	Employment classifications with overhead percentages.	Employees, Vacancies
Value Streams	Business capability groupings for portfolio reporting.	Projects
Lifecycle Stages	Project progress tracking (Planning, Active, Completed, etc.).	Projects
Cost Centres	Budget tracking categories.	Teams, Projects
Drivers	Business driver types for measuring project justification.	Projects
Exchange Rates	Currency conversion rates for multi-currency forecasting.	System-wide

---

ID Format

All entity IDs in Flowstate use the CUID format -- a collision-resistant unique identifier that looks like clx1a2b3c4d5e6f7g8h9. IDs are:

• Strings (not integers)
• Globally unique
• Assigned by the server (you never need to generate them)
• Stable (they never change after creation)