E-Budget

Documented design

• 65 domain modules, 62 controllers, 93 services and 56 repositories. Controllers are thin: none injects a repository or the data source.
• Services open transactions with DataSource.transaction and pass the EntityManager to repository methods, so multi-table writes commit or roll back together (about 100 transaction call sites across 67 services).
• Repositories only build queries: reads use the shared manager, writes use the transaction's manager, and domain errors are raised in services.
• Row locks (findForUpdate) guard read-modify-write steps, and sequential codes are generated inside the transaction so a failed insert rolls the counter back.
• Connection-level statement and idle-in-transaction timeouts are set in the shared data-source configuration.

Documented design

• Sign-in uses Microsoft Entra SSO through the MSAL authorization-code flow, with a random state value in a short-lived cookie guarding the callback.
• Access tokens are short-lived JWTs (15 minutes by default) carrying only a subject and an email; permissions are not in the token.
• Refresh tokens are random values stored only as SHA-256 hashes and rotated in a transaction with a row lock. Presenting a token that was already used counts as reuse and revokes all of that user's sessions.
• Global guards run in this order: JWT authentication, per-user throttling, then a feature-permission guard.
• Permissions are keyed by (module, resource, action): 3 modules, 65 resources and 10 actions. They are resolved from the database on every request, as the union of the user's roles reached through positions.
• Row-level scoping: a user's scope is a set of rows, each with up to five optional organizational dimensions. A record is in scope when it matches any row (OR of rows), and a row matches only when every dimension it specifies matches (AND of dimensions). A dimension left empty adds no constraint.
• Scoping is applied to reads (list and export queries, and a single out-of-scope record reads as not found), to writes (referenced parents must be in scope) and to imports (parent codes resolve within scope).

Documented design

• 35 template handlers. Most templates are real spreadsheets authored by analysts, which the engine fills with reference data and dropdown lists using ExcelJS; master-data templates are generated from scratch.
• Dropdowns are data-validation lists pointing at a reference sheet; number and percentage rules are enforced at import time, not inside the workbook.
• Template import validates every file and milestone first and reports all errors, each with a row, a code and a reason (codes E01 to E15). The write is one transaction, so an import is all-or-nothing.
• Input-norm uploads have a preview endpoint that validates without writing; the other imports have no preview step.
• Above 50,000 rows or 1,000,000 cells an export switches to a streaming writer that writes to a temporary file. The decision comes from a count query before any data is loaded.
• Hard caps: 1,000,000 rows per sheet and 2,000,000 rows per file. The writer yields to the event loop every 2,000 rows, and at most 2 large exports run at once per process (configurable).
• Uploads are limited to 5 MiB (10 MiB for input norms) and checked by declared type. A cap of 100 MB on uncompressed worksheet XML is read from the zip directory before the file is loaded, and 2 uploads run at once per process.
• Rows are read with eachRow rather than up to the declared row count, after a single styled cell near the last row exhausted memory.

Documented design

• Recalculation jobs use a transactional outbox: the job row is inserted with the EntityManager of the business operation (applying an input norm, approving a template or importing base prices), so it commits or rolls back with that operation. The default mode is asynchronous.
• Export jobs are a database-backed queue: the job row is inserted in its own short transaction (duplicate check, per-user and disk caps), not in a business transaction, so they are not an outbox.
• Workers for both tables poll on a timer and claim rows with FOR UPDATE SKIP LOCKED inside a transaction; no message broker is involved.
• A heartbeat marks live jobs and stale ones are reclaimed (recalculation after 15 minutes, exports after 5), up to 3 attempts. Recalculation retries transient database errors; exports have no automatic retry.
• State writes are conditional on the job id, status and attempt number, so a superseded run cannot overwrite a newer one. Export files are written per attempt and renamed into place.
• Exports offer status polling, regeneration (permissions are rechecked) and a download restricted to the job's owner. Files expire after a configurable time (24 hours by default) and a scheduled job purges them.
• BullMQ with Redis is used only for the email queue.

Documented design

• Suggested figures are derived for people costs (a unit cost per headcount group and month across 23 cost fields), non-people costs and selling prices. Inputs are approved source data and configurable norms held in the input-norm tables.
• When several norm rows are equally specific for a case, the calculation does not pick one: it collects the conflicts, lists up to 20, writes nothing and fails the whole recalculation, keeping the previous suggested data.
• A nested transaction (a SAVEPOINT) lets only the recalculation roll back: the action that triggered it, such as approving a norm edit, still succeeds and a failed job is recorded.
• Reports aggregate money with exact integer arithmetic at a scale of one millionth, and reject invalid numbers instead of treating them as zero.

Documented design

• Sensitive amounts (the new-hire cost norm and the suggested salary and bonus costs) are encrypted through HashiCorp Vault's transit engine and stored as ciphertext. An encryption failure raises an error instead of falling back to plaintext.
• Reading them requires being on a whitelist of permitted users and presenting a reveal token. A per-person access code is emailed once and stored only as an argon2 hash. The token lasts 15 minutes, is bound to a user and a scope, and can be revoked for everyone.
• Every rejected unlock returns the same error, and a dummy argon2 verification evens out the work done on each path; the audit log keeps the real reason. Sensitive export files need the same re-authentication to download.
• 431 hand-written migrations, because the migration generator cannot express partial-index predicates; schema synchronization is disabled and a test asserts it.
• Partial unique indexes apply only to rows not yet soft-deleted, so unique keys stay reusable. NULLS NOT DISTINCT is used where optional columns are part of a key, and bulk upserts use ON CONFLICT.
• Money columns are PostgreSQL numeric; no float column types are used.
• 180 domain error codes carry a stable code in every error response. The catalog is a convention with the frontend, not a machine-readable export.

Documented design

• Up to three approval levels. Approvers are resolved from the submitter's data-scope rows, and rows with the same approver chain form one route.
• A level opens only when the lower levels of its route are approved; any rejection rejects the record, and the record is approved when every step of every route is approved.
• Approving and rejecting are limited to the step's approver, and a missing or inactive approver configuration is reported as an error.
• Notification email is sent after the transaction commits, through the BullMQ email queue; a failure is logged and the decision stays committed.