# posguru-co-uk/finance-core architecture

> Architecture diagram of the GitHub repository posguru-co-uk/finance-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/posguru-co-uk/finance-core
- Repository: https://github.com/posguru-co-uk/finance-core

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram A — Library Module Architecture
  %% =========================
  subgraph A["Diagram A — Library Module Architecture (Static Dependency View)"]
    direction TB

    subgraph A0["Runtime Consumers (External)"]
      direction TB
      NodeApp["Node.js App (Backend)\n(Express/service)"]:::external
      ReactApp["React App (Browser)\n(webpack/vite/etc.)"]:::external
    end

    subgraph A1["@posguru/finance-core (Source - TypeScript)"]
      direction TB

      PublicAPI["src/index.ts\n(Public API Facade / Barrel Export)"]:::public

      subgraph A2["Domain Modules"]
        direction TB
        Invoice["src/invoice/index.ts\n(Invoice Domain Module)"]:::module
        Profile["src/profile/index.ts\n(Profile Domain Module)"]:::module
        Utils["src/utils.ts\n(Shared Utilities)"]:::module
      end

      subgraph A3["Profile: data-models (Types/DTOs)"]
        direction TB
        DMDir["src/profile/data-models/\n(Submodule Directory)"]:::group
        DMIndex["src/profile/data-models/index.ts\n(Models Barrel)"]:::module

        subgraph A3a["Model Files"]
          direction TB
          Admin["admin.ts\n(Admin model)"]:::model
          User["user.ts\n(User model)"]:::model
          Staff["staff.ts\n(Staff model)"]:::model
          Partner["partner.ts\n(Partner model)"]:::model
          Device["device.ts\n(Device model)"]:::model
          Driver["driver.ts\n(Driver model)"]:::model
          Location["location.ts\n(Location model)"]:::model
        end

        subgraph A3b["Structural Files"]
          direction TB
          Constants["constants.ts\n(Constants)"]:::model
          ServiceTypes["serviceTypes.ts\n(Service Types)"]:::model
          TypeDefs["type.ts\n(Type Definitions)"]:::model
          DMReadme["readme.md\n(Data-models Documentation)"]:::doc
        end
      end

      InvoiceReadme["src/invoice/README.md\n(Invoice Documentation)"]:::doc
    end

    %% Consumer -> Public API
    NodeApp -->|"imports/require()"| PublicAPI
    ReactApp -->|"imports"| PublicAPI

    %% Public API -> domain modules
    PublicAPI -->|"re-exports"| Invoice
    PublicAPI -->|"re-exports"| Profile
    PublicAPI -->|"re-exports"| Utils

    %% Profile -> data-models
    Profile -->|"imports/types"| DMIndex
    DMDir -->|"contains"| DMIndex

    %% data-models barrel -> model files
    DMIndex -->|"exports"| Admin
    DMIndex -->|"exports"| User
    DMIndex -->|"exports"| Staff
    DMIndex -->|"exports"| Partner
    DMIndex -->|"exports"| Device
    DMIndex -->|"exports"| Driver
    DMIndex -->|"exports"| Location
    DMIndex -->|"exports"| Constants
    DMIndex -->|"exports"| ServiceTypes
    DMIndex -->|"exports"| TypeDefs
    DMIndex -->|"docs"| DMReadme

    %% Shared utils usage (possible/expected)
    Invoice -->|"uses"| Utils
    Profile -->|"uses"| Utils

    %% Domain documentation relationships
    Invoice -->|"docs"| InvoiceReadme
  end

  %% =========================
  %% Diagram B — Build & Distribution Pipeline
  %% =========================
  subgraph B["Diagram B — Build & Distribution Pipeline (Artifact Flow View)"]
    direction TB

    subgraph B1["Authoring Inputs"]
      direction TB
      SrcTree["src/**/*.ts\n(TypeScript Source Tree)"]:::repo
      PkgJson["package.json\n(npm Package Contract / Entry Points)"]:::config
    end

    subgraph B2["Build Toolchain"]
      direction TB
      TS["TypeScript Compiler\n(transpile + declarations)"]:::tool
      Vite["Vite (Library Mode)\n(bundle ESM/CJS)"]:::tool
      TSConfig["tsconfig.json\n(Declaration Generation Config)"]:::config
      ViteConfig["vite.config.ts\n(Vite Library Bundler Config)"]:::config
    end

    subgraph B3["Build Outputs (dist/)"]
      direction TB
      DistDir["dist/\n(Published Artifacts)"]:::repo

      ESM["dist/sdk.esm.js\n(ESM Bundle)"]:::artifact
      CJS["dist/sdk.cjs\n(CommonJS Bundle)"]:::artifact

      subgraph B3a["Type Declarations (.d.ts)"]
        direction TB
        DtsIndex["dist/index.d.ts\n(Public API Types)"]:::artifact
        DtsUtils["dist/utils.d.ts\n(Utilities Types)"]:::artifact
        DtsInvoice["dist/invoice/index.d.ts\n(Invoice Types)"]:::artifact
        DtsProfile["dist/profile/index.d.ts\n(Profile Types)"]:::artifact
        DtsProfileDMDir["dist/profile/data-models/\n(Profile Data-model Types Dir)"]:::artifact
        TypesIndex["dist/types/index.d.ts\n(Additional Generated Types Output)"]:::artifact
      end
    end

    subgraph B4["Distribution"]
      direction TB
      Npm["npm Registry\n(@posguru/finance-core)"]:::external
    end

    %% Build flows
    SrcTree -->|"inputs"| TS
    TSConfig -->|"configures"| TS
    SrcTree -->|"entrypoints"| Vite
    ViteConfig -->|"configures"| Vite
    PkgJson -->|"drives exports/types"| Vite
    PkgJson -->|"drives exports/types"| TS

    TS -.->|"produces .d.ts"| DtsIndex
    TS -.->|"produces .d.ts"| DtsUtils
    TS -.->|"produces .d.ts"| DtsInvoice
    TS -.->|"produces .d.ts"| DtsProfile
    TS -.->|"produces .d.ts"| DtsProfileDMDir
    TS -.->|"produces .d.ts"| TypesIndex

    Vite -.->|"bundles ESM"| ESM
    Vite -.->|"bundles CJS"| CJS

    %% dist grouping
    DistDir -->|"contains"| ESM
    DistDir -->|"contains"| CJS
    DistDir -->|"contains"| DtsIndex
    DistDir -->|"contains"| DtsUtils
    DistDir -->|"contains"| DtsInvoice
    DistDir -->|"contains"| DtsProfile
    DistDir -->|"contains"| DtsProfileDMDir
    DistDir -->|"contains"| TypesIndex

    %% Publish/distribute
    DistDir -.->|"published"| Npm

    %% Consumer resolution
    Npm -.->|"install"| NodeApp
    Npm -.->|"install"| ReactApp
    NodeApp -->|"resolves"| CJS
    NodeApp -->|"types"| DtsIndex
    ReactApp -->|"resolves"| ESM
    ReactApp -->|"types"| DtsIndex
  end

  %% =========================
  %% Click Events (from component mapping)
  %% =========================
  click PublicAPI "https://github.com/posguru-co-uk/finance-core/blob/main/src/index.ts"
  click DtsIndex "https://github.com/posguru-co-uk/finance-core/blob/main/dist/index.d.ts"
  click Invoice "https://github.com/posguru-co-uk/finance-core/blob/main/src/invoice/index.ts"
  click InvoiceReadme "https://github.com/posguru-co-uk/finance-core/blob/main/src/invoice/README.md"
  click DtsInvoice "https://github.com/posguru-co-uk/finance-core/blob/main/dist/invoice/index.d.ts"
  click Profile "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/index.ts"
  click DtsProfile "https://github.com/posguru-co-uk/finance-core/blob/main/dist/profile/index.d.ts"
  click DMDir "https://github.com/posguru-co-uk/finance-core/tree/main/src/profile/data-models/"
  click DMIndex "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/index.ts"
  click Admin "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/admin.ts"
  click User "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/user.ts"
  click Staff "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/staff.ts"
  click Partner "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/partner.ts"
  click Device "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/device.ts"
  click Driver "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/driver.ts"
  click Location "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/location.ts"
  click Constants "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/constants.ts"
  click ServiceTypes "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/serviceTypes.ts"
  click TypeDefs "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/type.ts"
  click DMReadme "https://github.com/posguru-co-uk/finance-core/blob/main/src/profile/data-models/readme.md"
  click DtsProfileDMDir "https://github.com/posguru-co-uk/finance-core/tree/main/dist/profile/data-models/"
  click Utils "https://github.com/posguru-co-uk/finance-core/blob/main/src/utils.ts"
  click DtsUtils "https://github.com/posguru-co-uk/finance-core/blob/main/dist/utils.d.ts"
  click ViteConfig "https://github.com/posguru-co-uk/finance-core/blob/main/vite.config.ts"
  click TSConfig "https://github.com/posguru-co-uk/finance-core/blob/main/tsconfig.json"
  click ESM "https://github.com/posguru-co-uk/finance-core/blob/main/dist/sdk.esm.js"
  click CJS "https://github.com/posguru-co-uk/finance-core/blob/main/dist/sdk.cjs"
  click PkgJson "https://github.com/posguru-co-uk/finance-core/blob/main/package.json"
  click TypesIndex "https://github.com/posguru-co-uk/finance-core/blob/main/dist/types/index.d.ts"

  %% =========================
  %% Styles
  %% =========================
  classDef external fill:#ffedd5,stroke:#c2410c,stroke-width:2px,color:#7c2d12
  classDef public fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px,color:#0b3a8a
  classDef module fill:#bfdbfe,stroke:#1e40af,stroke-width:1.5px,color:#0b2a6f
  classDef model fill:#e0f2fe,stroke:#0369a1,stroke-width:1.25px,color:#0c4a6e
  classDef tool fill:#dcfce7,stroke:#15803d,stroke-width:2px,color:#14532d
  classDef artifact fill:#e5e7eb,stroke:#374151,stroke-width:1.5px,color:#111827
  classDef doc fill:#f3e8ff,stroke:#7e22ce,stroke-width:1.5px,color:#581c87
  classDef config fill:#fef9c3,stroke:#a16207,stroke-width:1.5px,color:#713f12
  classDef repo fill:#f1f5f9,stroke:#475569,stroke-width:1.5px,color:#0f172a
  classDef group fill:#e2e8f0,stroke:#334155,stroke-width:1.5px,color:#0f172a
```
