Skip to main content

Billing app

Internal app that calculates customer invoices: billing run per month, year plan, clients and charge lines. Repo: InsFocusSystems/billing.

Architecture​

  • backend/src/InsFocus.Billing.Api — ASP.NET API. BillingService.cs turns engine output into API views (billing run, plan, customers). DTOs in Dtos.cs.
  • backend/src/InsFocus.Billing.Domain — billing engine (BillingEngine.cs), model, legacy pricing conversion (LegacyPricing.cs).
  • backend/src/InsFocus.Billing.Data — storage. CSV (CsvPricingRepository) or SQL Server (SqlServerPricingRepository). Both load through PricingTables.cs.
  • frontend/ — Angular app. Billing run page: frontend/src/app/pages/billing-run/.
  • data/*.csv — CSV data set in the repo (lines, components, component values, quantities, products, charge types, invoices…).
  • SQL schema changes ship as EF Core migrations in backend/src/InsFocus.Billing.Data/Sql/Migrations/. The Data project has its own design-time factory, so it is its own startup project:
    cd backend
    dotnet ef migrations add <Name> --project src/InsFocus.Billing.Data --output-dir Sql/Migrations

Lifecycle​

  1. Work on a branch cut from origin/main.
  2. Open a PR. CI runs verify and image.
  3. The PR is merged (merge commit) into main. Each merge into main runs the "CI / deploy" workflow, which deploys to production.

Configuration​

  • Storage is set in appsettings.json: Billing:Storage (csv) and Billing:DataDirectory.
  • Auto-merge is disabled on the repo. Claude Code merges a PR only when Daniel says so (gh pr merge <n> --merge).

UI library and theme​

  • Frontend uses PrimeNG 20.4.0 on Angular 20.3, with primeicons 7, @angular/cdk and @angular/animations.
  • Theme: Aura from @primeuix/themes 1.2.5, with a custom preset BillingPreset in frontend/src/app/core/theme.ts (definePreset(Aura, …)). It is registered with providePrimeNG in app.config.ts.
  • Primary colour is azure #2466e0 (dark mode #5c9bff). Sidebar is royal blue #16306b. Amber marks flags and unsaved changes. Red marks errors and deletes.
  • App colour tokens live in frontend/src/styles.scss. PrimeNG styles sit in the primeng CSS layer, so styles.scss always wins.
  • Light, system and dark modes. Dark mode is the .app-dark class on <html>.
  • Font: IBM Plex Sans + IBM Plex Sans Hebrew + IBM Plex Mono, served locally via @fontsource. Fonts and PrimeIcons are loaded as global styles in angular.json.
  • angular.json budgets (warning only): main bundle 1 MB, per-component style 16 kB.
  • Shared pieces in frontend/src/app/shared/: date input (keeps the API's yyyy-MM-dd strings), appTrackEdits directive (unsaved-changes detection), <app-amount> (large money figures).
  • Notifications and confirmations use PrimeNG toast and confirm dialog.
  • Settings page: VAT and FX markup are entered as percentages, stored as ratios (0.18).

Billing run page​

  • Header shows only Net to invoice, VAT and Discounts given. Flagged lines are found through the "Flagged only" filter and flag icons in the table.
  • Client filter lists every active client. A client with nothing to bill shows an empty table ("No invoices for this month.").
  • Type and product filters list the whole catalog (charge_types.csv, products.csv), not only values present in the month.
  • Component breakdown (expanded line) columns: Name, Type, Product, Unit, Amount, Price, Notes, Total.
    • Price stays in the quoted period, e.g. ₪165 / month.
    • Amount is units × billed periods, e.g. 41 users on a quarterly bill → 123. Amount × price = total.
    • Notes hold the calculation: (17 = 42 − 25 included) × 3 months, (2 packs of 10 = 25 − 5 included). With nothing included: 18 × 3 months.
    • Mid-period quantity change: note says quantity changed during the period.
    • Tiered, usage and percentage components show an average price per unit.
    • Last row is labelled Total (was Net).
    • Table fills the row width. Name and Notes take the spare width and wrap.
  • Mark invoiced dialog has an Amount invoiced field, in the row's currency.
    • VAT clients type the amount including VAT (label "ILS, incl. VAT 18%"). Non-VAT clients: label "no VAT".
    • Prefilled with the calculated amount (incl. VAT where VAT applies). A hint shows the calculated amount when the typed one differs.
    • API: DocumentInvoiceRequest has an optional Amount. Left out → the calculated amount is stored.
  • Invoice record stores gross = the amount exactly as typed. net = gross ÷ (1 + VAT rate), e.g. 44,000 → 37,288.14 at 18%. Without VAT, gross = net. net_home uses the row's FX rate.
    • The Invoiced tile and home-currency totals use net.
    • Invoice history shows the typed amount, with "incl. VAT · net …" under it for VAT clients.
    • Invoices from before gross existed show their net amount.
  • "Amount differs" chip on a row whose active invoice does not match the calculated amount (compared incl. VAT). Hover shows both numbers. Replaces the old "amount changed" chip.
  • "Amount differs" checkbox in the filter bar (after the Invoiced dropdown) shows only rows with that chip. Line count and net total follow the filter.

Charge types​

  • Charge type sits on each price row, not on the line.
  • perpetual_license, works, project and hours are removed from the catalog. expenses is renamed to other.

Year plan page​

  • Chart only. No summary cards and no "Show workbook values under each cell" checkbox.
  • Workbook mismatches are still highlighted. Hovering a cell shows the workbook value. Highlighting applies in Invoices view only.
  • Client and type filters, same as the billing run: active clients in invoicing order, every type in the catalog. The chart, table and totals row follow the filters.
  • Type filter matches a line if any of its charge types matches.
  • Client filter uses the client id, so a client that splits invoices across entities shows all its entities.
  • Invoices/MRR toggle (same button group as the client editor). MRR view shows each line's monthly MRR; Total columns add up the year's MRR.
  • Filters sit below the chart.
  • Chart (frontend/src/app/shared/month-chart.ts, used only here) is half its original height (viewBox 110), with 3 gridlines. Top right shows the year total ("Total invoiced ₪…").
  • Client currency: filtered to one client whose shown lines are all in one non-ILS currency → chart, MRR view, client total row, footer row and Excel export total row show that currency, summed without FX. The ILS total stays in the "Total ILS" column. Chart note reads "EUR · client currency, no FX". The currency comes from the lines, not the client's default currency. Mixed currencies or no client selected → ILS.
  • Simulate from today button, shown for years after the current one:
    • Lines running today that end before the viewed year is over ignore their end date and keep billing at today's terms.
    • Lines that ended before today stay ended. Price rows keep their own end dates (a price row that ends is often followed by a new one; extending it would double-bill).
    • Runs on a copy of the contracts; saved data is never changed.
    • UI: button stays highlighted, a yellow note gives the count of extended lines, each extended line has a "simulated" chip (hover: real end date). Chart is labelled "simulated"; the Excel export says so in file name and footer. Going to the current year or earlier turns it off.
    • API: GET /plan?year=<y>&simulate=true, handled by RunOn in BillingService.cs. PlanRowDto.ExtendedFrom holds the ignored end date.
  • Plan API (PlanRowDto) returns per row: monthly MRR, planning FX rate and client id. Row sums × rate equal the API's monthly invoiced and MRR totals.

Amendments​

  • Amendments (dated price overrides) are retired. On data load they convert to dated price steps ("From date …") on the component.
  • The converted step shows in the line editor and can be edited or deleted. A note is added to the line's history.

Decisions​

  • 2026-10-07 — Redesign the frontend on PrimeNG 20 (Aura + custom BillingPreset) with light and dark modes. Why: modern, consistent UI across all pages.
  • 2026-10-07 — Primary colour switched to azure blue #2466e0 (was: petrol teal #0e7470). Why: a brighter, happier look.
  • 2026-10-07 — Billing run header shows only Net to invoice, VAT and Discounts given (was: also Gross incl. VAT, catch-ups, flagged lines).
  • 2026-10-21 — Billing run client filter lists all active clients. Why: a client with nothing to bill should still be selectable.
  • 2026-10-21 — Breakdown shows monthly price × amount (units × periods) for quarterly bills quoted per month (was: tripled price). Invoice totals unchanged. Why: price must match the quote.
  • 2026-10-21 — Breakdown gets separate Unit, Amount, Price and Notes columns. Why: the calculation was mixed into the amount.
  • 2026-10-21 — Breakdown last row renamed Total (was Net). Notes use the (billable = total − included) × N months format. Table is full width.
  • 2026-10-22 — Type and product filters list the whole catalog. Why: options with no lines that month were missing.
  • 2026-10-22 — Convert amendments to dated price steps on data load (PR #16). Why: the editor stopped showing amendments but the engine still applied them, so prices were billed that nobody could see or remove.
  • Backfill — Simplify charge line pricing and the catalog: charge type moves to the price row; unused charge types removed; expenses renamed to other.
  • Backfill — Year plan gets client/type filters and an Invoices/MRR toggle; side panel removed (PR #18).
  • 2026-10-25 — Year plan: chart only (cards and workbook checkbox removed), client/type filters, Invoices/MRR toggle (PR #18). Plan API returns per-line MRR and FX rate so filtered totals are computed client-side.
  • 2026-10-22 — Clients get an order number (auto-numbered, reorderable on the Clients page) for the order invoices are prepared (PR #17). The billing run is not sorted by it yet.
  • 2026-11-08 — Year plan chart at half height, showing the year's invoiced total (was: no totals in the chart) (PR #23).
  • 2026-11-08 — Mark invoiced dialog stores the amount the user types; for VAT clients it is typed incl. VAT and stored as gross, net derived from it (was: calculated amount only) (PR #23). Why: the invoice must keep the real invoiced number.
  • 2026-11-08 — Invoices get a nullable gross column: invoices.csv column and EF migration 20261108143722_InvoiceGross (PR #23).
  • 2026-11-08 — Billing run gets an "Amount differs" filter checkbox (PR #23).
  • 2026-11-08 — Year plan filtered to one foreign-currency client shows totals in that currency (PR #23).
  • 2026-11-08 — Year plan "Simulate from today" for future years (PR #23). Why: lines ending this year left 2027+ plans partial.
  • 2026-11-08 — PR #23 merged on Daniel's call before its CI check finished. The InvoiceGross migration first ran on SQL Server in the main deploy.

Gotchas​

  • Problem: a line bills a different price than the editor shows (e.g. retainer billed ₪4,500, editor shows ₪2,000). Cause: a hidden amendment in the live data. Fix: amendments now load as dated price steps; delete the step in the editor if it is wrong.
  • Problem: a dated step bills in advance in the period's invoice; an amendment billed as a catch-up after its date. Converting moves the timing (same yearly total). Lines on "Next period" change policy now bill the change in the current quarter.
  • Problem: npm install of PrimeNG fails with ERESOLVE (@angular/animations pins an exact @angular/core patch). Fix: install with --legacy-peer-deps at the existing Angular patch, then a plain npm install. npm ci (used by the Dockerfile) then works without flags.
  • Problem: the old unsaved-changes detection listened to native input events; PrimeNG select, datepicker and number fields do not fire them. Fix: the appTrackEdits directive watches NgModel changes instead.
  • Problem: p-drawer renders outside app-root, so component :host ::ng-deep styles miss it. Fix: drawer styles live in styles.scss.
  • Problem: running the API locally rewrites data/*.csv on load. Documenting one invoice also rewrites about eight CSV files, not just invoices.csv. Fix: git restore data (or git checkout -- data/) before committing.
  • Problem: a local main far behind origin/main (and with unpushed commits) causes heavy conflicts. Fix: always branch from origin/main; never force-push main.

Open​

  • Year plan cell colours by invoice state, with a legend (branch claude/plan-invoiced-cells) — not merged yet.