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
- Upload and activate the plugin. On activation it creates three database tables (see section 6).
- 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.
- 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
| Field | Values / notes |
|---|---|
| Type | Client project or side-project |
| Status | Active, Paused, Archived |
| Target €/h | Hourly rate you aim for; compared against the effective rate |
| Target hours/month | Shown next to the hours logged this month |
| Color | Used in charts and tables |
| Links | Optional 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:
| Recurrence | How it is counted |
|---|---|
| One-off | The full amount in the month of its date. |
| Monthly | The full amount every month from its date until its end date (or indefinitely). |
| Yearly | Amortized 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.
| Plugin | Link a project to | What is imported |
|---|---|---|
| GrowthProjects | A workspace | Monthly 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. |
| GrowthInvoices | A client | Monthly 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
| Column | Type | Notes |
|---|---|---|
| id / user_id | BIGINT | Owner is the WordPress user |
| name / description | VARCHAR(191) / TEXT | |
| type | VARCHAR(20) | cliente | sideproject |
| status | VARCHAR(20) | activo | pausado | archivado |
| hourly_rate / monthly_hours_target | DECIMAL | Targets |
| color | VARCHAR(7) | Hex color |
| gproj_workspace_id / gi_client_id | BIGINT | Optional integration links (0 = none) |
| created_at | DATETIME |
Table: {prefix}fb_transactions
| Column | Type | Notes |
|---|---|---|
| id / project_id / user_id | BIGINT | |
| kind | VARCHAR(10) | ingreso (income) | gasto (expense) |
| amount | DECIMAL(12,2) | Always stored as a positive value |
| concept | VARCHAR(191) | |
| recurrence | VARCHAR(10) | unico | mensual | anual |
| txn_date / end_date | DATE | end_date only for recurring movements |
| created_at | DATETIME |
Table: {prefix}fb_hours
| Column | Type | Notes |
|---|---|---|
| id / project_id / user_id | BIGINT | |
| period | VARCHAR(7) | YYYY-MM; unique per project |
| hours | DECIMAL(7,2) | |
| note | TEXT |
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.
| Action | Purpose | Key POST fields |
|---|---|---|
gbal_save_project | Create or update a project | id (optional), name, description, type, status, hourly_rate, monthly_hours_target, color, gproj_workspace_id, gi_client_id |
gbal_delete_project | Delete a project and all its data | id |
gbal_save_transaction | Create or update a movement | id (optional), project_id, kind, amount, concept, recurrence, txn_date, end_date |
gbal_delete_transaction | Delete a movement | id |
gbal_save_hours | Set the hours for a month (upsert) | project_id, period (YYYY-MM), hours, note |
gbal_delete_hours | Delete an hours record | id |
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.
I don’t see the GrowthProjects / GrowthInvoices link fields.
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.