Technical documentation for GrowthBalance — a project profitability tracker for freelancers, agencies and side-projects. This page covers how the plugin works, setup, the shortcode, the calculation model, integrations with GrowthProjects and GrowthInvoices, the data model, and AJAX actions.

Version: 1.1.0  |  Requires: WordPress 6.0+, PHP 7.4+  |  Text domain: growthbalance

1. Overview — how it works

GrowthBalance answers one question per project: is this worth my time? For each project you record income, expenses and hours worked; the plugin turns them into a monthly series, a cumulative balance, an effective hourly rate and a set of viability messages.

  • 100% front end — the whole app runs from the [growthbalance] shortcode. wp-admin only holds a small settings screen to choose the app page.
  • Private per user — every project, movement and hours record belongs to the WordPress user who created it. Each logged-in user sees only their own data.
  • Optional integrations — link a project to a GrowthProjects workspace (hours) and/or a GrowthInvoices client (income) and those figures are pulled in automatically, read-only.

2. Installation & setup

  1. Upload and activate the plugin. On activation it creates three database tables (see section 6).
  2. Go to GrowthBalance → Settings in wp-admin and either create the app page automatically (it is published with the shortcode inside) or assign an existing page that already contains it.
  3. Open that page while logged in and create your first project.

The settings screen requires manage_options. Using the app itself only requires being logged in.

3. Shortcode

[growthbalance]

The legacy alias [freelance_balance] renders the same app.

  • Visitors who are not logged in see a notice asking them to log in.
  • Logged-in users see the dashboard: global KPIs, charts and a table with every project (balance, hours this month vs. target, effective €/h).
  • Adding ?gb_project={id} to the page URL opens the project detail view: KPIs, income/expense and cumulative-balance charts, viability analysis, the hours log and the list of movements. Clicking a project in the dashboard does this for you.

Charts are rendered with Chart.js 4, loaded from the jsDelivr CDN. Assets are only enqueued on pages that render the shortcode.

4. Projects, movements & the calculation model

Projects

FieldValues / notes
TypeClient project or side-project
StatusActive, Paused, Archived
Target €/hHourly rate you aim for; compared against the effective rate
Target hours/monthShown next to the hours logged this month
ColorUsed in charts and tables
LinksOptional GrowthProjects workspace and GrowthInvoices client (section 5)

Movements (income & expenses)

Each movement has a kind (income or expense), amount, concept, date and a recurrence, which decides how it is spread over months:

RecurrenceHow it is counted
One-offThe full amount in the month of its date.
MonthlyThe full amount every month from its date until its end date (or indefinitely).
YearlyAmortized as amount ÷ 12 every month from its date until its end date (or indefinitely).

This monthly-equivalent model means a €120/year hosting plan shows up as a €10/month cost, so side-projects with annual subscriptions are compared fairly against monthly income.

Hours

Hours are logged per project and per month (one record per month, with an optional note). If the project is linked to a GrowthProjects workspace, the tracked hours from that workspace replace the manual ones.

Metrics

  • Balance = total income − total expenses, from the first month with data until the current month.
  • Cumulative balance — running total month by month (the “have I recovered the investment yet?” line).
  • Effective €/h = balance ÷ total hours.
  • Monthly recurring net — recurring income minus recurring expenses active in the current month.

Viability analysis

The project detail view turns those numbers into plain-language messages, for example:

  • Losing X/month in recurring costs, and how many months the current balance covers (runway).
  • Generating X/month of net recurring income (sustainable project).
  • Negative accumulated balance: the investment has not been recovered yet.
  • Effective €/h below or above your target rate.

5. Integrations

Integrations are read-only and detected at runtime: GrowthBalance never writes to the other plugins’ tables. The link fields only appear when the other plugin is installed.

PluginLink a project toWhat is imported
GrowthProjectsA workspaceMonthly hours: the sum of completed time entries on every task in that workspace (including tasks inside its folders and lists). Replaces manual hours for that project.
GrowthInvoicesA clientMonthly income: the total of that client’s invoices with status issued, partially paid or paid, grouped by issue date. Drafts, quotes and proformas are excluded. Added on top of manual income movements.

Together they close the loop: hours tracked in GrowthProjects and invoices issued in GrowthInvoices give you the real effective hourly rate of each client without entering anything twice.

6. Data model

Three tables are created (with the site’s table prefix). Every row stores a user_id and all queries are scoped to the current user.

Table: {prefix}fb_projects

ColumnTypeNotes
id / user_idBIGINTOwner is the WordPress user
name / descriptionVARCHAR(191) / TEXT
typeVARCHAR(20)cliente | sideproject
statusVARCHAR(20)activo | pausado | archivado
hourly_rate / monthly_hours_targetDECIMALTargets
colorVARCHAR(7)Hex color
gproj_workspace_id / gi_client_idBIGINTOptional integration links (0 = none)
created_atDATETIME

Table: {prefix}fb_transactions

ColumnTypeNotes
id / project_id / user_idBIGINT
kindVARCHAR(10)ingreso (income) | gasto (expense)
amountDECIMAL(12,2)Always stored as a positive value
conceptVARCHAR(191)
recurrenceVARCHAR(10)unico | mensual | anual
txn_date / end_dateDATEend_date only for recurring movements
created_atDATETIME

Table: {prefix}fb_hours

ColumnTypeNotes
id / project_id / user_idBIGINT
periodVARCHAR(7)YYYY-MM; unique per project
hoursDECIMAL(7,2)
noteTEXT

The fb_ prefix and the Spanish enum values come from the plugin’s origins as “Freelance Balance”; they are kept for backward compatibility. Deleting a project also deletes its movements and hours.

7. AJAX actions

All writes go through admin-ajax.php. Every action is logged-in only, requires the nonce field nonce for action gbal_nonce, and only touches records owned by the current user.

ActionPurposeKey POST fields
gbal_save_projectCreate or update a projectid (optional), name, description, type, status, hourly_rate, monthly_hours_target, color, gproj_workspace_id, gi_client_id
gbal_delete_projectDelete a project and all its dataid
gbal_save_transactionCreate or update a movementid (optional), project_id, kind, amount, concept, recurrence, txn_date, end_date
gbal_delete_transactionDelete a movementid
gbal_save_hoursSet the hours for a month (upsert)project_id, period (YYYY-MM), hours, note
gbal_delete_hoursDelete an hours recordid

8. FAQ & troubleshooting

The page says I must log in.

The app is per user, so it needs an authenticated WordPress user. Place the page behind login or send users to wp-login.php first.

Can my team share the same projects?

No. Data is private per WordPress user: each person who logs in gets their own independent set of projects. This makes it suitable for multi-user sites, but not for a shared team ledger.

They only appear when the other plugin is active and has at least one workspace (GrowthProjects) or client (GrowthInvoices) to link to. Install and activate it, create a workspace or client, then edit the project again.

My manual hours disappeared after linking a workspace.

When a project is linked to a GrowthProjects workspace that has tracked time, those hours become the single source of truth and replace the manual ones. Unlink the workspace to go back to manual hours; your manual records are not deleted.

Which currency does it use?

Amounts are displayed in euros.


Back to GrowthBalance product page.

Scroll to Top