Resource Cost Profile

The Resource Cost Profile module is where an organization defines the internal baseline financial cost for each team member. While Team Management handles access and identity, this screen handles the financial foundation for each user.

Why This Page Exists

Defining resource costs is a critical step for unlocking Orbit's financial features. If an employee logs 10 hours on a project, Orbit needs to know exactly how much those 10 hours cost the company internally in order to calculate the profit margin against what you invoice the client.

The data configured here directly feeds into Project Resource Financial Control, Resource Billing, and Profitability Analytics, allowing the platform to automatically calculate internal costs versus billable revenue across all active projects.

---

From Cost Profile to Project Profitability

Understanding how the system uses this data will make managing it intuitive.

1. Admin Sets Cost Profile: You define how much an employee costs.
2. Rate Saved: The system records this rate and the date it became effective.
3. Employee Logs Timesheet: The employee tracks time against a project.
4. System Finds Active Rate: The system looks back at the cost profile to find the exact rate active on the day the timesheet was logged.
5. Internal Cost Calculated: It multiplies the hours worked by the effective hourly rate.
6. Profitability Calculated: The internal cost is compared against the project's billable revenue to determine the live profit margin.

---

Before you begin

Before configuring resource costs, keep the following in mind:

• Users must exist: You can only assign costs to users who have already been invited and added via Team Management.
• Permissions: You must have the org.users.cost.view permission to see this screen. To make changes or bulk-apply costs, you need the org.users.cost.manage permission.
• Default Monthly Hours: When calculating an effective hourly rate for salaried employees, the system uses an organizational default of 160 hours per month.

---

Understanding the Resource Cost Profile screen

The main screen provides a comprehensive ledger of all team members and their current financial footprint.

📸 Screenshot placeholder: RCP-01

Capture: The main Resource Cost Profile screen showing the filters and the table of users with varying cost types.

Suggested caption: The Resource Cost Profile acts as a centralized financial ledger for your workforce.

Field & Control Reference

Here is a quick reference guide to every major column and control on the page.

UI Element	Purpose	When to Use	Result
Filters (Top)	Narrow down the user list	When looking for users missing a cost profile, or searching by name	Instantly filters the visible rows
Checkboxes (Left)	Select users for bulk actions	When applying a raise to a whole department	Activates the Bulk Apply panel at the bottom
Budget Head	Assigns the cost to a department	To track which department budget is paying for this resource	Groups the user's costs in financial reports
Type	Defines the compensation structure	Select between Hourly, Monthly Salary, or Fixed Contract	Determines how the Effective Hourly rate is calculated
Base Cost	The monetary amount paid	Setting their actual salary or rate	Saves the raw financial value
Calculated Hourly	The standardized hourly rate	(System calculated) Used by timesheets	Determines the exact internal cost per hour worked
Effective From	The date the cost applies	When scheduling a future raise or backdating a correction	Timesheets logged after this date will use this new rate
Clock Icon	View the Timeline Audit	When investigating a user's salary history	Expands a horizontal timeline showing all historical changes

---

Setting up a User's Cost Profile

You can configure costs individually or apply them in bulk to multiple users at once.

Updating a single user (Inline Editing)

The table is designed for rapid data entry. You do not need to open a separate edit screen.

1. Navigate to Organization Settings → Team Management.
2. Click the Resource Cost Profile tab (or navigate directly to /org/resource-cost).
3. Locate the user you want to update.
4. Click the Budget Head dropdown to assign a financial category (or leave it as Unallocated).
5. Click the Type dropdown to select Hourly, Monthly, or Fixed.
6. Click into the Base Cost field and type the amount.
7. Set the Effective From date.

📸 Screenshot placeholder: RCP-02

Capture: A row where the Base Cost has been edited but the user hasn't clicked away yet, showing the yellow PENDING badge.

Suggested caption: Unsaved text changes display a yellow Pending badge until you click outside the field.

[!TIP] Saving Changes: Dropdown selections (Budget Head, Type) save immediately. Text fields (Base Cost, Effective Date) show a yellow PENDING badge when changed, and save automatically as soon as you click outside the input field.

How "Calculated Hourly" works

No matter how an employee is paid, Orbit requires an hourly rate to calculate project profitability when they log timesheets.

• Hourly: The Calculated Hourly rate perfectly matches the Base Cost.
• Monthly: The system automatically divides the Base Cost by the organization's standard monthly hours (default 160) to determine the Calculated Hourly rate.
• Fixed Contract: The system cannot guess how many hours a fixed contractor will work, so you must manually type in the Calculated Hourly rate next to the Base Cost.

Bulk Updating multiple users

If you have hired a team of contractors at the same rate, or if you are moving an entire department to a new Budget Head, you can update them all at once.

1. Check the box on the left side of each user's row. (You can use the filters to easily find a specific group).
2. The Bulk Apply panel will appear at the bottom of the screen.
3. In the panel, select the new Budget Head, Cost Type, Base Cost, and Effective Date.
4. Click Bulk Apply.

📸 Screenshot placeholder: RCP-03

Capture: The Bulk Apply panel at the bottom of the screen with several checkboxes ticked above it.

Suggested caption: Select multiple users to apply identical cost changes simultaneously.

[!WARNING] Bulk applying a change will immediately create a new historical cost entry for every selected user starting on the chosen Effective Date.

---

Viewing Cost History (Timeline Audit)

Resource costs often change over time due to raises, promotions, or contract renegotiations. Orbit preserves the entire history of a user's cost profile.

If a user logs time on a project in January, their January cost rate is applied. If they get a raise in February, their February time entries will use the new rate, but January's financial reports remain intact.

To view a user's cost history:

1. Locate the user in the list.
2. Click the Clock Icon (Timeline Audit) on the right side of their row.
3. The row will expand to reveal a horizontal timeline showing every historical cost change, the date it became active, and the exact amount. The most recent entry will be highlighted as Current.

📸 Screenshot placeholder: RCP-04

Capture: An expanded row showing the Timeline Audit, with nodes representing historical rates and the current active rate.

Suggested caption: The Timeline Audit provides a permanent, immutable record of salary progression.

---

Common Scenarios

Here are some realistic business examples of how this page is used.

Scenario 1: Applying an Annual Department Raise

In January, the entire Engineering department receives a standard 5% raise.

1. Use the Search or Filter to isolate the Engineering team.
2. Select the checkboxes for all visible Engineering members.
3. Use the Bulk Apply panel to set their new Base Cost and set the Effective From date to January 1st.
4. From January 1st onward, all timesheets logged by these engineers will automatically pull the higher rate, while last year's profitability reports remain unchanged.

Scenario 2: Backdating a Forgotten Rate Change

A contractor's hourly rate increased three weeks ago, but the administrator forgot to update the system.

1. Find the contractor's row.
2. Change the Base Cost to the new, higher rate.
3. Change the Effective From date to exactly three weeks ago.
4. The system will automatically recalculate the internal cost of all timesheets the contractor submitted over the past three weeks using the updated rate.

---

Troubleshooting

Problem	Possible Reason	What to Check / Do
I typed a new Base Cost, but the yellow Pending badge won't go away.	The field is still active.	Changes to text fields save on blur. Click anywhere outside the text box to trigger the save.
I cannot see the Bulk Apply panel.	You haven't selected any users, or you lack permissions.	Select at least one checkbox on the left. If checkboxes are missing or disabled, you do not have the org.users.cost.manage permission.
I set a Monthly Salary, but the hourly rate looks wrong.	Your organization uses a different standard for monthly hours.	The system defaults to 160 hours/month. This calculation is a fixed organizational standard.
I cannot change the Effective Hourly rate.	The user is not a Fixed Contract type.	You can only manually type the Effective Hourly rate if the Type dropdown is set to Fixed. For Hourly and Monthly, the system calculates it automatically.
I made a mistake. How do I delete a cost entry?	Cost history is immutable.	You cannot "delete" a cost entry. If you made a mistake, simply change the Base Cost and Effective Date again to overwrite or correct the current active state.

---

FAQ

Do I have to enter a cost for everyone?
No, but any user without a cost profile who logs timesheets will register as costing the organization $0.00, which will artificially inflate your Project Profitability metrics.

Who can see this information?
Only administrators with the org.users.cost.view permission can see this screen. Standard employees cannot view their own or others' internal cost profiles.

Does changing a rate today affect timesheets from yesterday?
No. Because of the Effective From date, the system maintains a perfect historical record. If you change a rate today (Effective today), yesterday's timesheets will still use yesterday's rate.

---

Technical Reference — Developers & QA

This section contains technical implementation details for testing and maintenance.

• Application Route: /org/resource-cost (also resolves via /org/users?tab=cost_profile)
• Frontend Component: src/routes/org/UserCostProfileTab.tsx
• Primary Data Queries:
  • ['allUserCosts'] via userService.listAllLatestCosts
  • ['budgetHeads'] via projectService.getOrgConfig
• Mutations:
  • userService.updateUserCost (handles both inline single saves and bulk array saves).
• Permissions:
  • View access: org.users.cost.view (determines access to the route/tab).
  • Edit access: org.users.cost.manage (determines if inputs are disabled and if the bulk action panel renders).

Technical Note: Effective Hourly Cost Calculation

The payload sent to updateUserCost includes both base_cost and effective_hourly_cost. The frontend calculates the effective_hourly_cost before transmission based on the cost_type:

• hourly: effective_hourly_cost = base_cost
• monthly_salary: effective_hourly_cost = base_cost / monthlyHours (defaults to 160)
• fixed_contract: effective_hourly_cost is a manual input field driven by the effHourly state variable, independent of base_cost.

QA Verification Checklist

When testing this component, ensure the following flows are verified:

• Inline Save (Dropdowns): Changing Budget Head or Type instantly fires a save mutation.
• Inline Save (Inputs): Modifying Base Cost, Effective Hourly (for fixed), or Date triggers a yellow Pending badge. Clicking outside the input fires the save mutation.
• Calculations: Changing Type dynamically updates the Calculated Hourly column display (read-only for Hourly/Monthly, input for Fixed).
• Timeline: Clicking the audit icon correctly expands the history row, sorted chronologically with the newest active node highlighted.
• Bulk Apply: Selecting multiple rows and submitting the Bulk panel correctly applies the exact exact same payload to all selected user IDs.
• Permissions: Users without org.users.cost.manage should see disabled inputs and no checkboxes.