# barchart/portfolio-public architecture

> Architecture diagram of the GitHub repository barchart/portfolio-public, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/barchart/portfolio-public
- Repository: https://github.com/barchart/portfolio-public

## Overview

This repository publishes a shared portfolio domain library and a JavaScript client SDK. The user-facing path is client code configuring a gateway, obtaining JWT credentials, and invoking Portfolio Service operations; shared models then define validation, transaction formatting, position calculations/grouping, summaries, and serialization. The README documents these package roles; source excerpts show gateway authentication setup and position-processing internals. Many gateway operations and schema relationships are not fully excerpted, so uncertain links are omitted.

Main entry points: [`packages/portfolio-api-common/lib/processing/PositionContainer.js`](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/PositionContainer.js) (Position container), [`packages/portfolio-client-js/lib/gateway/PortfolioGateway.js`](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-client-js/lib/gateway/PortfolioGateway.js) (Portfolio gateway), [`packages/portfolio-api-common/lib/processing/PositionItem.js`](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/PositionItem.js) (Position item), [`packages/portfolio-api-common/lib/data/InstrumentType.js`](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/data/InstrumentType.js) (Domain types)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client SDK"]
  node_config["Environment config<br/>[Configuration.js]"]
  node_gateway["Portfolio gateway"]
  node_jwt["JWT provider<br/>[JwtProvider.js]"]
end

subgraph group_domain["Portfolio Domain"]
  node_failure["Failure types"]
  node_types["Domain types<br/>[InstrumentType.js]"]
  node_transactions["Transaction rules"]
  node_avg["Average price"]
  node_valuation["Valuation calculator"]
  node_txnformat["Transaction formatter"]
  node_instrument["Instrument provider"]
  node_summaryframe["Summary frames"]
  node_summaryfmt["Summary formatter"]
  node_websocket["WebSocket actions"]
end

subgraph group_processing["Position Processing"]
  node_container["Position container"]
  node_group["Position group<br/>[PositionGroup.js]"]
  node_item["Position item<br/>[PositionItem.js]"]
  node_leveldef["Grouping definition"]
  node_binding["Group binding"]
end

subgraph group_wire["Serialization"]
  node_portfolio_schema["Portfolio schema<br/>[PortfolioSchema.js]"]
  node_position_schema["Position schema<br/>[PositionSchema.js]"]
  node_summary_schema["Summary schema"]
  node_transaction_schema["Transaction schema"]
  node_report_schema["Report availability"]
end

node_caller(("SDK consumer"))
node_service["Portfolio Service"]

node_caller -->|"invokes SDK"| node_gateway
node_gateway -.->|"uses environment"| node_config
node_gateway -->|"requests token"| node_jwt
node_jwt -->|"reads token host"| node_config
node_gateway -->|"sends REST requests"| node_service
node_jwt -->|"requests impersonation token"| node_service
node_transactions -->|"validates instrument"| node_types
node_txnformat -->|"calculates average price"| node_avg
node_item -->|"calculates basis price"| node_avg
node_item -->|"calculates valuation"| node_valuation
node_item -->|"branches by instrument"| node_types
node_group -->|"creates binding"| node_binding
node_group -->|"uses grouping rules"| node_leveldef
node_container -->|"constructs groups"| node_group
node_container -->|"manages items"| node_item
node_container -->|"uses summary frames"| node_summaryframe
node_container -->|"uses tree definitions"| node_leveldef
node_summaryfmt -.->|"formats frame data"| node_summaryframe
node_portfolio_schema -.->|"describes portfolio data"| node_position_schema
node_position_schema -->|"encodes instrument type"| node_types
node_summary_schema -->|"encodes frame"| node_summaryframe
node_transaction_schema -->|"encodes instrument type"| node_types
node_report_schema -->|"encodes summary frame"| node_summaryframe

click node_config "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-client-js/lib/common/Configuration.js"
click node_gateway "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-client-js/lib/gateway/PortfolioGateway.js"
click node_jwt "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-client-js/lib/security/JwtProvider.js"
click node_failure "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/api/failures/PortfolioFailureType.js"
click node_types "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/data/InstrumentType.js"
click node_transactions "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/data/TransactionValidator.js"
click node_avg "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/calculators/AveragePriceCalculator.js"
click node_valuation "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/calculators/ValuationCalculator.js"
click node_txnformat "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/formatters/TransactionFormatter.js"
click node_container "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/PositionContainer.js"
click node_group "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/PositionGroup.js"
click node_item "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/PositionItem.js"
click node_leveldef "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/definitions/PositionLevelDefinition.js"
click node_binding "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/binding/PositionGroupBinding.js"
click node_instrument "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/providers/InstrumentProvider.js"
click node_summaryframe "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/data/PositionSummaryFrame.js"
click node_summaryfmt "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/formatters/PositionSummaryFormatter.js"
click node_portfolio_schema "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/PortfolioSchema.js"
click node_position_schema "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/PositionSchema.js"
click node_summary_schema "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/PositionSummarySchema.js"
click node_transaction_schema "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/TransactionSchema.js"
click node_report_schema "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/reports/BrokerageReportAvailabilitySchema.js"
click node_websocket "https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/websockets/WebsocketActionType.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_config,node_gateway,node_jwt toneBlue
class node_failure,node_types,node_transactions,node_avg,node_valuation,node_txnformat,node_instrument,node_summaryframe,node_summaryfmt,node_websocket toneAmber
class node_container,node_group,node_item,node_leveldef,node_binding toneMint
class node_portfolio_schema,node_position_schema,node_summary_schema,node_transaction_schema,node_report_schema toneRose
class node_caller,node_service toneIndigo
```

## Components

### Client SDK

- [Environment config](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-client-js/lib/common/Configuration.js): `packages/portfolio-client-js/lib/common/Configuration.js`
- [Portfolio gateway](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-client-js/lib/gateway/PortfolioGateway.js): `packages/portfolio-client-js/lib/gateway/PortfolioGateway.js`
- [JWT provider](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-client-js/lib/security/JwtProvider.js): `packages/portfolio-client-js/lib/security/JwtProvider.js`

### Portfolio Domain

- [Failure types](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/api/failures/PortfolioFailureType.js): `packages/portfolio-api-common/lib/api/failures/PortfolioFailureType.js`
- [Domain types](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/data/InstrumentType.js): `packages/portfolio-api-common/lib/data/InstrumentType.js`
- [Transaction rules](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/data/TransactionValidator.js): `packages/portfolio-api-common/lib/data/TransactionValidator.js`
- [Average price](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/calculators/AveragePriceCalculator.js): `packages/portfolio-api-common/lib/calculators/AveragePriceCalculator.js`
- [Valuation calculator](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/calculators/ValuationCalculator.js): `packages/portfolio-api-common/lib/calculators/ValuationCalculator.js`
- [Transaction formatter](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/formatters/TransactionFormatter.js): `packages/portfolio-api-common/lib/formatters/TransactionFormatter.js`
- [Instrument provider](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/providers/InstrumentProvider.js): `packages/portfolio-api-common/lib/providers/InstrumentProvider.js`
- [Summary frames](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/data/PositionSummaryFrame.js): `packages/portfolio-api-common/lib/data/PositionSummaryFrame.js`
- [Summary formatter](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/formatters/PositionSummaryFormatter.js): `packages/portfolio-api-common/lib/formatters/PositionSummaryFormatter.js`
- [WebSocket actions](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/websockets/WebsocketActionType.js): `packages/portfolio-api-common/lib/websockets/WebsocketActionType.js`

### Position Processing

- [Position container](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/PositionContainer.js): `packages/portfolio-api-common/lib/processing/PositionContainer.js`
- [Position group](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/PositionGroup.js): `packages/portfolio-api-common/lib/processing/PositionGroup.js`
- [Position item](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/PositionItem.js): `packages/portfolio-api-common/lib/processing/PositionItem.js`
- [Grouping definition](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/definitions/PositionLevelDefinition.js): `packages/portfolio-api-common/lib/processing/definitions/PositionLevelDefinition.js`
- [Group binding](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/processing/binding/PositionGroupBinding.js): `packages/portfolio-api-common/lib/processing/binding/PositionGroupBinding.js`

### Serialization

- [Portfolio schema](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/PortfolioSchema.js): `packages/portfolio-api-common/lib/serialization/PortfolioSchema.js`
- [Position schema](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/PositionSchema.js): `packages/portfolio-api-common/lib/serialization/PositionSchema.js`
- [Summary schema](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/PositionSummarySchema.js): `packages/portfolio-api-common/lib/serialization/PositionSummarySchema.js`
- [Transaction schema](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/TransactionSchema.js): `packages/portfolio-api-common/lib/serialization/TransactionSchema.js`
- [Report availability](https://github.com/barchart/portfolio-public/blob/master/packages/portfolio-api-common/lib/serialization/reports/BrokerageReportAvailabilitySchema.js): `packages/portfolio-api-common/lib/serialization/reports/BrokerageReportAvailabilitySchema.js`

### Other components

- **SDK consumer**
- **Portfolio Service**

## Connections

- SDK consumer → Portfolio gateway: invokes SDK (evidence: `packages/portfolio-client-js/lib/gateway/PortfolioGateway.js`)
- Portfolio gateway → Environment config: uses environment (evidence: `packages/portfolio-client-js/lib/gateway/PortfolioGateway.js`)
- Portfolio gateway → JWT provider: requests token (evidence: `packages/portfolio-client-js/lib/gateway/PortfolioGateway.js`)
- JWT provider → Environment config: reads token host (evidence: `packages/portfolio-client-js/lib/security/JwtProvider.js`)
- Portfolio gateway → Portfolio Service: sends REST requests (evidence: `packages/portfolio-client-js/lib/gateway/PortfolioGateway.js`)
- JWT provider → Portfolio Service: requests impersonation token (evidence: `packages/portfolio-client-js/lib/security/JwtProvider.js`)
- Transaction rules → Domain types: validates instrument (evidence: `packages/portfolio-api-common/lib/data/TransactionValidator.js`)
- Transaction formatter → Average price: calculates average price (evidence: `packages/portfolio-api-common/lib/formatters/TransactionFormatter.js`)
- Position item → Average price: calculates basis price (evidence: `packages/portfolio-api-common/lib/processing/PositionItem.js`)
- Position item → Valuation calculator: calculates valuation (evidence: `packages/portfolio-api-common/lib/processing/PositionItem.js`)
- Position item → Domain types: branches by instrument (evidence: `packages/portfolio-api-common/lib/processing/PositionItem.js`)
- Position group → Group binding: creates binding (evidence: `packages/portfolio-api-common/lib/processing/PositionGroup.js`)
- Position group → Grouping definition: uses grouping rules (evidence: `packages/portfolio-api-common/lib/processing/PositionGroup.js`)
- Position container → Position group: constructs groups (evidence: `packages/portfolio-api-common/lib/processing/PositionContainer.js`)
- Position container → Position item: manages items (evidence: `packages/portfolio-api-common/lib/processing/PositionContainer.js`)
- Position container → Summary frames: uses summary frames (evidence: `packages/portfolio-api-common/lib/processing/PositionContainer.js`)
- Position container → Grouping definition: uses tree definitions (evidence: `packages/portfolio-api-common/lib/processing/PositionContainer.js`)
- Summary formatter → Summary frames: formats frame data
- Portfolio schema → Position schema: describes portfolio data
- Position schema → Domain types: encodes instrument type (evidence: `packages/portfolio-api-common/lib/serialization/PositionSchema.js`)
- Summary schema → Summary frames: encodes frame (evidence: `packages/portfolio-api-common/lib/serialization/PositionSummarySchema.js`)
- Transaction schema → Domain types: encodes instrument type (evidence: `packages/portfolio-api-common/lib/serialization/TransactionSchema.js`)
- Report availability → Summary frames: encodes summary frame (evidence: `packages/portfolio-api-common/lib/serialization/reports/BrokerageReportAvailabilitySchema.js`)