Budget & Capex: how the app works

Version 5.0 · a guide to what the app does, who can do what, how a budget moves from draft to approved, and how each field you change affects the numbers in the reports.

The screens are in Portuguese or English (PT/EN switch at the top). This guide uses the English names, with the Portuguese name in italics where it helps.

1. The app at a glance

Each department prepares one budget per year. A budget is a list of cost and revenue lines grouped by category. Each line has last year's actual amount, this year's base amount and an adjustment, and it is split over the months. From those lines the app produces two documents, on screen and in PDF and Excel: the Capex and Costs report (Capex e Custos) and the Monthly budget (Orçamento mensal).

Pages of the app and who sees them EVERY USER Budgets (Orçamentos) List per department and year New year · Import Excel · Excel template Archived versions → open a budget to edit, approve, download, email, request reopening Budget page Lines by category, totals, year rate Workflow steps and status Download ▾ · Send by email · Upload Excel History (changes and reopen requests) Delete (administrators only) Reports (Relatórios) Capex and Costs · Monthly budget Choose language and site View online · PDF · Excel Send by email My profile: name, language, password APPROVERS Categories (Categorias) Their own department's categories ADMINISTRATORS Departments and their workflows Categories and sites all departments Users role, department, language Activity (Atividade) who did what, filters, CSV Email sending account · mail log
Pages in the top menu. Approvers also see everything every user sees, and administrators see everything.

2. What runs on the server

The app runs on one server on your network with Docker. People open it in a browser at http://<server>:8080. Nothing needs to be installed on the PCs.

Containers and how they connect Browsers PCs on the network SERVER · DOCKER COMPOSE "budget-capex" web (Caddy) screens, HTTPS, passes /api on api (Python) rules, calculations, PDF and Excel db PostgreSQL: all the data backup nightly dump + one before every upgrade Mail server SMTP: send IMAP: Sent copy backups/ folder on disk :8080 emails "back up first"
Four containers. Your data lives in the db container's volume, not in the app folder, so replacing the folder with a new version keeps it. The dashed arrow is the request the api makes before it changes the database during an upgrade.

3. What is stored

Main records and how they relate Department e.g. IT, F&B · name, active User role, department, language belongs to one department Workflow step ordered; approved by the dept's approvers or named users Category PT and EN name, cost/revenue, order, show when empty Budget (year) year, title, year rate, status, current step, source file Line category, site, prior actual, base, adjustment, months, remarks Site Sagres, Quinta, Chiado, Oriente Reopen request reason, status, decision Shared by the whole app Activity log: every action by every user Mail settings: the sending account (passwords encrypted) Mail log: every email sent and whether it arrived Archived versions: replaced budgets, read-only Sites are shared by all departments many many
Solid arrows: "has many". Dashed: a line points to one category and optionally one site. A department's categories are its own, so an IT budget never shows F&B lines.

4. Roles and permissions

Every user has one role and belongs to one department. Everyone can see and export every budget. Only the budget's own department can change or approve it.

WhatViewerEditorApproverAdmin
View budgets and reports, download PDF / Excelallallallall
Send reports by email (once email is set up)yesyesyesyes
Request reopening of an approved budget (with reason)yesyesyesyes
Create, import, edit a draft budget; upload a changed filenoown deptown deptany
Submit a draft for reviewnoown deptown deptany
Approve or return a workflow stepnonoown dept*own dept*
Reopen directly, accept or decline reopen requestsnonoown deptany
Manage categoriesnonoown deptany
Delete a budget (any status, typed confirmation)nononoyes
Departments, workflows, users, sites, email settings, activity and mail logsnononoyes

* A workflow step can instead name specific users who approve it; then only those users can approve that step, whatever their role. An administrator can always return a budget in review to draft.

5. A budget's life cycle

Budget statuses and the actions that move between them Create: New year (empty or copied from an earlier year) or Import Excel Draft editable by the department In review Step 1 e.g. IT director Step 2 e.g. Finance … n Approved locked; view, export and email only Submit Approve (last step) Return to draft (approver of the step, or admin) Reopen: approver/admin with a reason, or an accepted reopen request Archived 🔒 replaced by an upload; read-only Upload a file for the same year Delete: administrators only, any status
Only a draft can be changed. Each approval moves the budget to the next workflow step; the last approval makes it Approved. A department with no steps configured is approved in one step by its approvers.

6. How the numbers are calculated

Every total in the app and in the reports is built from the lines, in this order. Change any input on the left, and everything to its right follows.

From a line's fields to the report totals YOU TYPE THE APP WORKS OUT YOU SEE Prior-year actual number or 12*839,67 Base (without adjustment) number or calculation Adjustment year rate · % · factor · none Year rate (budget) Inflation + adjustments % Months 12 · chosen months · typed Factor e.g. 1,055 or 1,15 Adjusted amount base × factor, to cents Change € and % adjusted − prior 12 monthly amounts in cents, add up exactly Category totals sum of its lines (filtered by site if chosen) Budget totals costs and revenue, prior → adjusted, change Capex and Costs report year totals and charts Monthly budget Jan … Dec per line only for "year rate"
With Monthly amounts (typed months) the path is different: the year total is simply the sum of the twelve months, and Base and Adjustment are not used.

The adjustment and the factor

Adjustment (Ajuste)Factor usedExample, base 96 532,00 €
Year rate (Taxa do ano)1 + the budget's year raterate 5,5 % → × 1,055 = 101 841,26 €
Percent (%)1 + adjustment value ÷ 100value 15 → × 1,15 = 111 011,80 €
Factor (Fator ×)the adjustment valuevalue 2,055 (hardware price rise) → 198 373,26 €
None (Sem ajuste)196 532,00 €
Worked example (IT 2027, "Mobile phone subscriptions")
Prior-year actual 96 532,00 € Base 96 532,00 € Adjustment Factor × 1,15 Adjusted 96 532,00 × 1,15 = 111 011,80 € Change 111 011,80 − 96 532,00 = +14 479,80 € (+15,00 %) Months chosen: Jan–Apr → 27 752,95 € each, May–Dec 0

Rounding rules

Typing amounts

Amount fields work like Excel: 12*839,67+3292,56 or =5512*12. Both 1 234,56 and 1,234.56 are understood. The calculation is kept, so you can see later how a figure was built.

7. Every field and what it changes

On a budget

FieldWhat it doesWhat changes when you edit it
YearThe budget year; one current budget per department and year.Column headings ("2026 actual", "2027 adjusted"), report titles, file names.
TitleName shown in lists and reports.Budget list, report headers, email subject suggestion.
Inflation + adjustments (%) (Taxa do ano)The year rate.Every line whose adjustment is "Year rate": their factor, adjusted amount, months, and so all category and budget totals and both reports. Lines with %, factor or none are not affected.
Copy from an earlier year (when creating)Starts the new year from another year's lines.Each copied line's prior actual and base both start at last year's adjusted amount; adjustment type, months and site are kept. Replace the actual with the real figure.

On a line

FieldWhat it doesWhat changes when you edit it
Line (name) and DescriptionLabels.Text in the budget and the reports only.
CategoryWhich group the line belongs to (your department's categories).Moves the amounts from one category total to another: category pages and charts in Capex and Costs, grouping in the Monthly budget. Budget totals stay the same, unless the category is a revenue category, in which case the amount counts as revenue instead of cost.
Site (Unidade)Sagres, Quinta, Chiado, Oriente, or Group.What appears when a page or report is filtered by site. "Group" lines appear only in the all-sites view.
Prior-year actualWhat was spent last year.The "prior" column, change € and change %, category and budget prior totals, and the comparison charts. Does not change the new year's amount.
Base (sem ajuste)The new year's amount before the adjustment.Adjusted amount → months → every total for the new year → both reports.
Adjustment and its valueHow the base becomes the adjusted amount (see the table above).Factor → adjusted amount → months → totals → reports.
Reason for adjustmentWhy it went up or down.Shown under the line and in the reports.
MonthsHow the year amount is spread: split over 12, split over chosen months, or typed monthly amounts.Only the Monthly budget's month columns and the monthly totals. The year total does not change (except with typed amounts, where the year total is the sum of the months).
RemarksFree notes.Shown on the line; no effect on numbers.

On a category

FieldWhat changes
Name (PT / EN)The heading in the language of the screen or the report.
Section: cost or revenueWhether its lines count in the cost totals or the revenue totals.
OrderThe order of categories on screen and in the reports.
Show when emptyWhether a category with no lines still appears (with zero) in the budget and reports.
ActiveInactive categories can't be chosen for new lines. Existing lines keep them. A category with lines can be deactivated, but not deleted.

8. Splitting a year into months

The three ways to split a line into months Split over 12 (Dividir por 12) · 12 000,00 € JanFebMarAprMayJunJulAugSepOctNovDec 1 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 0001 000 Split over chosen months (Dividir pelos meses escolhidos) · Jan–Apr ticked JanFebMarAprMayJunJulAugSepOctNovDec 3 0003 0003 0003 000 00000000 Monthly amounts (Valores mensais) · each month typed; the year total is their sum JanFebMarAprMayJunJulAugSepOctNovDec 5005002 000800800800001 6008008003 400
The first two keep the year total (base × adjustment) and only decide when it is spent. Quick buttons on the line pick a quarter (Q1–Q4) or a half-year (H1, H2). Switching a line from typed months to a split keeps its year total as the base.

9. Reports, downloads and email

Capex and Costs Capex e Custos

  • Totals: prior-year actual vs adjusted, change € and %
  • Chart of each category, last year vs this year
  • Chart of the change by category
  • One page per category with its lines and reasons
  • Summary table

Monthly budget Orçamento mensal

  • Every line with its twelve months and year total
  • Category subtotals and monthly totals
  • Option: include empty categories
  • Excel version keeps live formulas

On the Reports page you pick the budget, the language (Portuguese or English) and the site; the same choice applies to viewing online, PDF, Excel and email. On a budget page, Download ▾ offers the editable budget file and both reports, and Send by email lets you attach any of them. That works in every status, including draft and approved.

Sending by email asks for recipients (To, Cc, "send me a copy"), a subject and a message, and which files to attach. The email goes out from the account the administrator set up, a copy is saved in that mailbox's Sent folder, and the mail log records it.

10. Excel: template, download, re-upload

Download, change and upload a budget file Draft budget IT 2027 "Budget 2027" in the app Download ▾ Budget file Orcamento_IT_2027.xlsx Change it in Excel lines, amounts, months same file name Upload Excel pop-up: "The file already exists" · OK New current budget the lines from your file; same title "Budget 2027" "Loaded from Orcamento_IT_2027.xlsx" · editable draft Old version, archived 🔒 renamed "Budget 2027 (2026-10-28 23:00)" Orcamento_IT_2027_2026-10-28_2300.xlsx locked: view, export, email; admin may delete
Nothing is lost: the version you replace is kept, renamed with the date and time, and locked. Only a draft can be replaced. An approved or in-review budget must be reopened first. Archived versions are listed under Budgets → "Show archived versions".

Excel template (Budgets → Modelo Excel) gives a workbook for a department and year, blank or pre-filled from an existing budget, in PT or EN. It has an Instructions sheet and a Lines sheet with drop-down lists for category, site and adjustment, twelve month columns, and a last column Split over months where you can write 1-4 or Jan, Fev, Mar, Abr. Unknown categories are created on import; anything skipped is listed. The original "Budget para 2027" workbook layout can also be imported.

11. Reopening an approved budget

Reopen request flow Approved budget any user presses "Request reopening" Reason (mandatory) at least 5 characters; request is pending Approvers + admins see it on the budget, get an email Accept and reopen budget back to draft; requester emailed Decline reason required; stays approved; requester emailed
An approver or administrator of the department can also reopen directly with Reopen, giving a reason; that also answers an open request. One request can be pending at a time. All requests, decisions and reasons stay in the budget's History.

12. Admin: email, logs, backups, upgrades

Email → Sending account

  • SMTP server, port, security (STARTTLS 587 / SSL 465 / none), username and password
  • Sender address and name, reply-to, signature
  • Copy in the Sent folder over IMAP (found automatically, or named)
  • Test connection signs in only; Send test email sends one
  • Turning email on adds "Send by email" for everyone

Gmail already keeps its own copy, so turn the Sent-folder option off there.

Logs

  • Activity: sign-ins (and failed ones), every change to budgets and lines, imports, approvals, reopen requests, archiving, deletions, report views, downloads and emails, admin changes. Filter and export to CSV.
  • Email → Mail log: who sent what to whom, attachments, delivered or failed, Sent-folder copy saved or not. Export to CSV.

Backups

  • A database dump every night at BACKUP_TIME into backups/, kept BACKUP_KEEP_DAYS days
  • An extra one, …_before_upgrade.sql.gz, before every upgrade that changes the database
  • Restore: docker compose exec backup restore.sh /backups/<file>
  • Copy backups/ to another disk or NAS regularly

Upgrading to a new version

  1. Unzip the new version over the app folder, keeping .env and backups/
  2. Run docker compose up -d --build

The api asks for a backup, waits for it, then updates the database. If the backup fails, it does not upgrade. Never run docker compose down -v: -v deletes the data.

Budget & Capex · version 5.0.0 · guide written 28 October 2026.