README
¶
OPG SIRIUS SUPERVISION FINANCE HUB
Major dependencies
- Go (>= 1.22)
- docker compose (>= 2.26.0)
- sqlc (>=1.25.0)
- goose (3.20.0)
- htmx (2.0.0)
- pgx (5.5.5)
- validator (10.19.0)
Walkthrough
A walkthrough of this project has been written for the Golang Community of Practice, describing the package structure and some technical aspects of the codebase.
Installing dependencies locally:
(This is only necessary if running without docker)
yarn installgo mod download
Local development
The application ran through Docker can be accessed on localhost:8888/finance/clients/1/invoices.
To enable debugging and hot-reloading of Go files:
make up
Hot-reloading is managed independently for both apps and should happen seamlessly. Hot-reloading for web assets (JS, CSS, etc.) is also provided via a Yarn watch command.
Both the finance-hub (front end) and finance-api (back end) can be debugged independently, as they expose different
ports for Delve:
finance-hub: 2345finance-api: 3456
Generating the sqlc Store
The data access layer of finance-api is auto-generated with sqlc. It reads the database schema (specified in /migrations/)
to generate the models and queries in /finance-api/internal/store/queries/.
To generate these files after making changes, run make sqlc-gen.
Generating migrations
To generate migration files with goose, install it locally with brew install goose and run:
goose -dir ./migrations create <name-of-migration> sql
Or copy the up and down files and increment them.
Adding seed data
In general, look to keep tests self-contained by having them create (and clear) the data they require for testing. However, there are instances where we need to seed the data in advance in order to test it, such as where the method for adding the data is driven by Sirius, e.g. Cypress tests asserting on the client header.
To seed this data, add the inserts to /test-data.sql.
Run the unit/integration tests
make test
Run the Cypress tests
make cypress
Or to run interactively:
cd cypress
npx cypress open baseUrl=http://localhost:8888/finance
Run Trivy scanning
make scan
Architectural Decision Records
The major decisions made on this project are documented as ADRs in /adrs. The process for contributing to these is documented
in the first ADR.
HTMX & JS
This project uses HTMX to render partial HTML instead of reloading the whole page on each request.
However, this can mean that event listeners added on page load may fail to register/get deregistered when a partial is
loaded. To avoid this, you can force event listeners to register on every HTMX load event by putting them within the
htmx.onLoad function.
HTMX also includes a range of utility functions that can be used in place of more unwieldy native DOM functions.
Directories