How posguru-co-uk/finance-core works
What this project is (type + purpose)
This repo is an npm-published, universal TypeScript/JavaScript library named @posguru/finance-core, intended to be consumed by:
• Node.js backends (e.g., Express)
• React/front-end apps
Its purpose (per README) is “finance-related math functions,” but the file tree shows it’s already structured as a small SDK-style package with multiple domains/modules:
• src/invoice/*
• src/profile/* (with many data-models/*)
• src/utils.ts
• src/index.ts as the public entrypoint
It builds into dist/ with:
• dist/sdk.cjs (CommonJS bundle)
• dist/sdk.esm.js (ESM bundle)
• dist/**/*.d.ts (TypeScript type declarations)
How to read the file structure (architecture clues)
Key directories/files and what they imply:
Source code (authoring time)
• src/index.ts
Likely the single public export surface (barrel) re-exporting modules.
• src/invoice/index.ts + src/invoice/README.md
A self-contained Invoice domain module with its own documentation.
• src/profile/index.ts + src/profile/data-models/*
A Profile domain module containing many data model definitions (admin, device, driver, user, etc.). This smells like:
• shared DTO/type definitions
• constants/enums (constants.ts, serviceTypes.ts, type.ts)
• src/utils.ts
Shared helpers used across invoice/profile/math functions.
Build + distribution (consumption time)
• vite.config.ts
Indicates bundling via Vite (library mode typically) to produce ESM/CJS outputs.
• tsconfig.json
TS compilation + .d.ts generation.
• dist/
The published artifacts. Presence of both sdk.cjs and sdk.esm.js implies dual-module support.
• package.json / package-lock.json
The contract for consumers: entry points, exports, types, build scripts, dependencies.
What the “main components” are for diagramming
For this project, treat “components” as modules, entrypoints, build outputs, and consumer environments.
Runtime consumers (external to the library)
• Node.js app (Express/service)
• React app (browser bundle via webpack/vite/etc.)
Library public API layer
• src/index.ts (and dist/index.d.ts): the public surface area
• Potential subpath exports (implied by dist/invoice/index.d.ts, dist/profile/index.d.ts)
Internal domain modules
• Invoice module
• src/invoice/index.ts
• (and its internal functions/types)
• Profile module
• src/profile/index.ts
• src/profile/data-models/* (admin, user, staff, partner, device, driver, location, etc.)
• Shared Utilities
• src/utils.ts
Build/packaging toolchain
• TypeScript compiler (types + transpilation)
• Vite bundler (CJS + ESM bundles)
• npm registry publishing (distribution channel)
Because it’s a library, “data flow” is primarily import/dependency flow and build artifact flow.
Import/dependency flow (source-level)
• src/index.ts → src/invoice/index.ts
• src/index.ts → src/profile/index.ts
• src/profile/index.ts → src/profile/data-models/*
• src/invoice/index.ts → src/utils.ts (if used)
• src/profile/* → src/utils.ts (if used)
This shows the internal dependency graph and makes it easy to maintain a clean public API boundary.
Build flow (pipeline-level)
• src/**/*.ts → (TypeScript) → .d.ts in dist/**
• src/index.ts → (Vite bundler) → dist/sdk.esm.js
• src/index.ts → (Vite bundler) → dist/sdk.cjs
Consumption flow (runtime-level)
• React App → imports from @posguru/finance-core → uses dist/sdk.esm.js (typically)
• Node.js App → requires/imports @posguru/finance-core → uses dist/sdk.cjs or ESM depending on environment
• Both consumers → get typings from dist/**/*.d.ts
Barrel Export / Public Facade
• src/index.ts acts as a facade over internal modules.
Domain-oriented module boundaries
• invoice and profile are separate domains.
• profile/data-models is a “types/models submodule” used by profile (and possibly others).
Dual build targets
• ESM + CJS for universal consumption.
• .d.ts generation to support TS consumers.
As annotations or small labels on components:
• TypeScript (source authoring, typing)
• Vite (bundling)
• ESM/CJS outputs (dist/sdk.esm.js, dist/sdk.cjs)
• Type Declarations (dist/**/*.d.ts)
• npm (package distribution)
• Consumer environments: Node.js and Browser/React
Diagramming conventions to use (make it unambiguous)
Consistently:
Clear labels for each component
• Use exact names from the tree where possible:
• src/index.ts (Public API)
• src/profile/data-models/user.ts (User model)
• dist/sdk.esm.js (ESM bundle)
• dist/sdk.cjs (CJS bundle)
“Separate into as many components as possible” (practical decomposition for this repo)
• admin.ts, user.ts, staff.ts, partner.ts, device.ts, driver.ts, location.ts
• plus “structural” files: constants.ts, serviceTypes.ts, type.ts, index.ts
Do the same for:
• invoice/index.ts (and any implied invoice internals you discover)
• utils.ts
type surface explicitly:
• dist/index.d.ts
• dist/profile/data-models/*.d.ts
This matters because for a library, types are a first-class output and often the “real contract”.
To ensure accuracy, verify in src/index.ts (and package.json exports) which modules are actually public:
• If invoice and profile are exported as subpaths (e.g., @posguru/finance-core/invoice), show that explicitly as additional public entrypoints.
• If only src/index.ts is public, show invoice/profile as internal modules behind the facade.
That final check prevents a common mistake: diagramming internal modules as “public API” when they are not exported.