# spacious-team/investbook architecture

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

- Interactive diagram: https://gitdiagram.com/spacious-team/investbook
- Repository: https://github.com/spacious-team/investbook

## Overview

Investbook is a local investment-portfolio accounting application. Users import broker reports or enter transactions and events manually; the system stores normalized portfolio records and presents account, instrument, cash-flow, and return analyses, with Excel/HTML reports and Open Portfolio Format export. The README describes these capabilities, while sampled source confirms key persistence, foreign-exchange, sector, and form-service behavior. Broker-specific parsing and several report implementations were not sampled, so those branches are shown at subsystem level and their unverified links are dashed.

Main entry points: [`src/main/java/ru/investbook/repository`](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/repository) (Repositories), [`src/main/java/ru/investbook/web/forms/service`](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/web/forms/service) (Form services), [`src/main/java/ru/investbook/web/InvestbookReportController.java`](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/web/InvestbookReportController.java) (Portfolio reports), [`src/main/java/ru/investbook/entity/TransactionEntity.java`](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/TransactionEntity.java) (Transactions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data intake"]
  node_parser["Report parsers"]
  node_mail["Mailbox import"]
  node_openformat["Open format import"]
end

subgraph group_core["Portfolio core"]
  node_accounts[("Accounts and cash<br/>[AccountEntity.java]")]
  node_securities[("Securities")]
  node_transactions[("Transactions")]
  node_securityevents[("Security events")]
  node_repositories["Repositories"]
  node_converters["Entity converters"]
end

subgraph group_analytics["Analysis and reports"]
  node_fifo["FIFO positions"]
  node_fx["Exchange rates"]
  node_sectors["Sector allocation"]
  node_sectorlookup["Sector metadata"]
  node_reports["Portfolio reports"]
  node_composition["Account composition"]
  node_excel["Excel output"]
  node_html["HTML output<br/>[HtmlView.java]"]
end

subgraph group_interfaces["User interfaces"]
  node_manual["Manual entry"]
  node_formservices["Form services"]
  node_api["REST API"]
  node_export["Portfolio export"]
end

node_user(("Investor"))
node_brokerfiles["Broker reports"]
node_market{{"Market data"}}

node_user -->|"provides reports"| node_brokerfiles
node_brokerfiles -.->|"parsed by"| node_parser
node_user -->|"enters records"| node_manual
node_user -.->|"imports mail"| node_mail
node_user -.->|"imports portfolio"| node_openformat
node_parser -.->|"records trades"| node_transactions
node_parser -.->|"records balances"| node_accounts
node_manual -.->|"submits forms"| node_formservices
node_formservices -->|"saves transactions"| node_transactions
node_formservices -->|"saves events"| node_securityevents
node_formservices -->|"uses repositories"| node_repositories
node_api -->|"delegates persistence"| node_repositories
node_converters -->|"maps entities"| node_accounts
node_converters -->|"maps entities"| node_securities
node_repositories -->|"reads and writes"| node_accounts
node_repositories -->|"reads and writes"| node_securities
node_repositories -->|"queries trades"| node_transactions
node_repositories -->|"stores events"| node_securityevents
node_transactions -.->|"position basis"| node_fifo
node_fifo -->|"positions valued"| node_sectors
node_fx -->|"loads rates"| node_repositories
node_sectors -->|"reads sector data"| node_sectorlookup
node_sectorlookup -->|"queries metadata"| node_market
node_reports -->|"renders reports"| node_excel
node_reports -->|"renders reports"| node_html
node_composition -->|"gets allocation"| node_sectors
node_user -->|"views analysis"| node_reports
node_reports -->|"presents results"| node_user
node_user -.->|"requests export"| node_export
node_export -->|"builds portfolio"| node_openformat

click node_parser "https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/parser"
click node_mail "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/parser/MailboxReportParserService.java"
click node_openformat "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/openformat/v1_1_0/PortfolioOpenFormatV1_1_0.java"
click node_manual "https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/web/forms/controller"
click node_formservices "https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/web/forms/service"
click node_api "https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/api"
click node_accounts "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/AccountEntity.java"
click node_securities "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/SecurityEntity.java"
click node_transactions "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/TransactionEntity.java"
click node_securityevents "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/SecurityEventCashFlowEntity.java"
click node_repositories "https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/repository"
click node_converters "https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/converter"
click node_fifo "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/report/FifoPositionsFilter.java"
click node_fx "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/report/ForeignExchangeRateService.java"
click node_sectors "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/service/InvestmentProportionService.java"
click node_sectorlookup "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/service/SecuritySectorService.java"
click node_reports "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/web/InvestbookReportController.java"
click node_composition "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/web/AccountCompositionController.java"
click node_excel "https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/report/excel"
click node_html "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/report/html/HtmlView.java"
click node_export "https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/openformat/PortfolioOpenFormatController.java"

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_parser,node_mail,node_openformat toneBlue
class node_accounts,node_securities,node_transactions,node_securityevents,node_repositories,node_converters toneAmber
class node_fifo,node_fx,node_sectors,node_sectorlookup,node_reports,node_composition,node_excel,node_html toneMint
class node_manual,node_formservices,node_api,node_export toneRose
class node_user,node_brokerfiles,node_market toneIndigo
```

## Components

### Data intake

- [Report parsers](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/parser): `src/main/java/ru/investbook/parser`
- [Mailbox import](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/parser/MailboxReportParserService.java): `src/main/java/ru/investbook/parser/MailboxReportParserService.java`
- [Open format import](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/openformat/v1_1_0/PortfolioOpenFormatV1_1_0.java): `src/main/java/ru/investbook/openformat/v1_1_0/PortfolioOpenFormatV1_1_0.java`

### Portfolio core

- [Accounts and cash](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/AccountEntity.java): `src/main/java/ru/investbook/entity/AccountEntity.java`
- [Securities](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/SecurityEntity.java): `src/main/java/ru/investbook/entity/SecurityEntity.java`
- [Transactions](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/TransactionEntity.java): `src/main/java/ru/investbook/entity/TransactionEntity.java`
- [Security events](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/entity/SecurityEventCashFlowEntity.java): `src/main/java/ru/investbook/entity/SecurityEventCashFlowEntity.java`
- [Repositories](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/repository): `src/main/java/ru/investbook/repository`
- [Entity converters](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/converter): `src/main/java/ru/investbook/converter`

### Analysis and reports

- [FIFO positions](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/report/FifoPositionsFilter.java): `src/main/java/ru/investbook/report/FifoPositionsFilter.java`
- [Exchange rates](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/report/ForeignExchangeRateService.java): `src/main/java/ru/investbook/report/ForeignExchangeRateService.java`
- [Sector allocation](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/service/InvestmentProportionService.java): `src/main/java/ru/investbook/service/InvestmentProportionService.java`
- [Sector metadata](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/service/SecuritySectorService.java): `src/main/java/ru/investbook/service/SecuritySectorService.java`
- [Portfolio reports](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/web/InvestbookReportController.java): `src/main/java/ru/investbook/web/InvestbookReportController.java`
- [Account composition](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/web/AccountCompositionController.java): `src/main/java/ru/investbook/web/AccountCompositionController.java`
- [Excel output](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/report/excel): `src/main/java/ru/investbook/report/excel`
- [HTML output](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/report/html/HtmlView.java): `src/main/java/ru/investbook/report/html/HtmlView.java`

### User interfaces

- [Manual entry](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/web/forms/controller): `src/main/java/ru/investbook/web/forms/controller`
- [Form services](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/web/forms/service): `src/main/java/ru/investbook/web/forms/service`
- [REST API](https://github.com/spacious-team/investbook/tree/develop/src/main/java/ru/investbook/api): `src/main/java/ru/investbook/api`
- [Portfolio export](https://github.com/spacious-team/investbook/blob/develop/src/main/java/ru/investbook/openformat/PortfolioOpenFormatController.java): `src/main/java/ru/investbook/openformat/PortfolioOpenFormatController.java`

### Other components

- **Investor**
- **Broker reports**
- **Market data**

## Connections

- Investor → Broker reports: provides reports (evidence: `README.md`)
- Broker reports → Report parsers: parsed by
- Investor → Manual entry: enters records (evidence: `README.md`)
- Investor → Mailbox import: imports mail
- Investor → Open format import: imports portfolio
- Report parsers → Transactions: records trades
- Report parsers → Accounts and cash: records balances
- Manual entry → Form services: submits forms (evidence: `src/main/java/ru/investbook/web/forms/controller/SecurityDescriptionController.java`)
- Form services → Transactions: saves transactions (evidence: `src/main/java/ru/investbook/web/forms/service/TransactionFormsService.java`)
- Form services → Security events: saves events (evidence: `src/main/java/ru/investbook/web/forms/service/SecurityEventCashFlowFormsService.java`)
- Form services → Repositories: uses repositories (evidence: `src/main/java/ru/investbook/web/forms/service/TransactionFormsService.java`)
- REST API → Repositories: delegates persistence (evidence: `src/main/java/ru/investbook/api/AbstractEntityRepositoryService.java`)
- Entity converters → Accounts and cash: maps entities (evidence: `src/main/java/ru/investbook/converter/SecurityEventCashFlowConverter.java`)
- Entity converters → Securities: maps entities (evidence: `src/main/java/ru/investbook/converter/SecurityEventCashFlowConverter.java`)
- Repositories → Accounts and cash: reads and writes (evidence: `src/main/java/ru/investbook/repository/AccountRepository.java`)
- Repositories → Securities: reads and writes (evidence: `src/main/java/ru/investbook/repository/SecurityRepository.java`)
- Repositories → Transactions: queries trades (evidence: `src/main/java/ru/investbook/repository/TransactionRepository.java`)
- Repositories → Security events: stores events (evidence: `src/main/java/ru/investbook/web/forms/service/SecurityEventCashFlowFormsService.java`)
- Transactions → FIFO positions: position basis
- FIFO positions → Sector allocation: positions valued (evidence: `src/main/java/ru/investbook/service/InvestmentProportionService.java`)
- Exchange rates → Repositories: loads rates (evidence: `src/main/java/ru/investbook/report/ForeignExchangeRateService.java`)
- Sector allocation → Sector metadata: reads sector data (evidence: `src/main/java/ru/investbook/service/InvestmentProportionService.java`)
- Sector metadata → Market data: queries metadata (evidence: `src/main/java/ru/investbook/service/SecuritySectorService.java`)
- Portfolio reports → Excel output: renders reports (evidence: `src/main/java/ru/investbook/web/InvestbookReportController.java`)
- Portfolio reports → HTML output: renders reports (evidence: `src/main/java/ru/investbook/web/InvestbookReportController.java`)
- Account composition → Sector allocation: gets allocation (evidence: `src/main/java/ru/investbook/web/AccountCompositionController.java`)
- Investor → Portfolio reports: views analysis (evidence: `README.md`)
- Portfolio reports → Investor: presents results (evidence: `README.md`)
- Investor → Portfolio export: requests export
- Portfolio export → Open format import: builds portfolio (evidence: `src/main/java/ru/investbook/openformat/PortfolioOpenFormatController.java`)