Skip to content

Generated file. Source: docs/product_spec.en.md Edit the source document and run npm run docs:sync to refresh this published copy.

Product Specification

PM -> Developer Document

Field Value
Product Treasury Bond Calculator
Document class authoritative product specification
Document status active
Version 1.1
Last review 2026-03-24
Document owner Product Manager
Primary audience Developer
Document goal maintain a shared understanding of the product, scope, implementation status, and development direction, and make it easier to hand work off between stages

Table of Contents

  1. Purpose of the document and how to use it
  2. Product context and user problem
  3. Product vision and business goals
  4. Implementation status and scope map
  5. Source-of-truth map
  6. Product decisions currently in force
  7. User groups
  8. Product screens and their responsibilities
  9. Diagrams and visual materials
  10. Main user flows
  11. Input parameters and their meaning
  12. Rules for presenting and interpreting results
  13. Functional requirements
  14. Data requirements
  15. Product boundaries and layer responsibilities
  16. UX/UI requirements
  17. Non-functional requirements
  18. Product roadmap
  19. Dependencies and risks
  20. Acceptance criteria
  21. How to use this specification during handoff
  22. Open questions
  23. Related documents

1. Purpose of the Document and How to Use It

1.1 Why This Document Exists

This document is meant to:

  • describe the product from a business and usability perspective
  • indicate what is already implemented and what is only planned
  • give the developer a map of where to look for logic, data, and product decisions
  • support taking over work at any stage without guessing the current product state

1.2 What This Document Does Not Replace

This document does not replace:

  • technical documentation of the bond engine
  • documentation of concrete strategy logic
  • the separate product roadmap document
  • tests
  • the code implementation

These items are related to this specification, but their implementation details are not duplicated here.

1.3 How to Read This Document

For development work, the document should be read in this order:

  1. Implementation status and scope map
  2. Product decisions currently in force
  3. the section corresponding to the area being changed
  4. Related documents

1.4 Meaning of Statuses

The document uses the following statuses:

  • Implemented - the behavior exists in the current product
  • Implemented / disabled - the element exists in the product, but is intentionally not functionally active
  • Planned - the behavior is an approved direction, but has not yet been implemented
  • Out of scope - the behavior does not belong to the current scope

2. Product Context and User Problem

2.1 User Problem

Retail users interested in treasury bonds face several practical difficulties today:

  • they cannot quickly see which bond is best for their specific investment horizon
  • they do not understand how taxes, inflation, early redemption cost, and reinvestment affect the result
  • they do not have a simple way to compare different bonds year by year
  • source materials usually describe issuance parameters, but do not show the full investment outcome in a readable form

2.2 Why This Matters

This matters because the user:

  • is making a financial decision
  • may choose a bond that is suboptimal for their horizon
  • may incorrectly interpret the interest rate as the final return
  • may not understand that some costs and taxes are realized only at final settlement

2.3 Product Opportunity

The product has two levels of potential:

  1. a bond comparison calculator
  2. a foundation for a future portfolio product based on specific bond issues and investor history

3. Product Vision and Business Goals

3.1 Main Goal

Provide the user with a trustworthy, readable, and fast tool for comparing the profitability of investments in retail treasury bonds.

3.2 Detailed Goals

  • increase understanding of differences between bond types
  • make it easier to choose the best instrument for a given horizon
  • show both the final result and the path of the investment over time
  • prepare the product and data layer for future portfolio-oriented expansion

3.3 Long-Term Vision

Ultimately, the product should reach a state in which:

  • input data is partially updated automatically
  • the user can work with inflation scenarios
  • recurring investments can be modeled
  • there is an issuance database and a foundation for an investment portfolio
  • the user can also launch the calculator through an assistant that asks questions, fills the form, and runs the same simulation as manual mode

4. Implementation Status and Scope Map

4.1 Status of Product Modules

Area Status Notes
Bond selection for comparison Implemented Tiles and table, family-bond availability logic; without 800+ amount-cap enforcement
Investment parameters Implemented Amount, horizon, inflation, reference rate, 800+
Account type Implemented / disabled Visible in UI, no impact on calculations
Comparison chart Implemented Metric switching, bar/line mode, and support for the active global analysis mode
Results summary Implemented Table and tiles, ranking, column filters, and support for the active global analysis mode
Detailed yearly table Implemented Single-bond view and comparison view, column filters, bond selection, two data-grouping layouts, and support for the active global analysis mode: investment progression / year-by-year liquidation; its local switch UI controls the same shared state as the chart
How the calculator works page Implemented In-app documentation for the user
Product roadmap page Implemented Communication of development direction
Calculator input assistant Planned Future conversational entry path to the same form and engine
IKE / IKZE logic Out of scope UI prepared, logic postponed
Automatic market data Planned Reference rate, issuance terms
Inflation predictions and scenarios Planned Roadmap stages
Bond portfolio Planned Long-term direction

4.2 Status of Bond Logic Families

Family / strategy Status Notes
OTS Implemented Dedicated quarterly strategy
ROR, DOR Implemented Shared monthly-income family
TOS, EDO, ROS, ROD Implemented Shared annual-accumulation family
COI Implemented annual-payout family

4.3 What Is in the Current MVP+ Scope

The current product is considered to be:

  • a complete comparison calculator for all supported bonds
  • a UI with correct result interpretation
  • in-product documentation support
  • a stable architectural base for further development

4.4 Handoff Map for Main Areas

Area Where to check product-wise Where to check technically What usually must be updated when changed
Bond selection this document, section 13 selection.ts, store, bond selection component UI, tooltips, eligibility rules
Investment parameters this document, section 11 store, form, engine normalization UI, help text, validation
Result interpretation this document, section 12 strategy family docs, results components UI, tooltips, technical docs
Chart and summary this document, sections 8, 12, 16 results components, store UI, metrics, filters
Yearly table this document, sections 8, 12, 20 table component, event contract UI, filters, status messages
Bond logic this document, sections 6 and 12 bond_engine_architecture.md and per-bond docs technical docs, tests, prompt
Data and roadmap this document, sections 14, 18 future data layer roadmap, acceptance criteria, docs

5. Source-of-Truth Map

5.1 Source of Truth for Product Requirements

5.1a Source of Truth for the Product Roadmap

5.2 Source of Truth for Engine Architecture

5.2a Source of Truth for the Result Model Contract

5.2aa Source of Truth for the Interpretation / Analysis Layer

5.2b Source of Truth for Data and Persistence Contracts

  • data_persistence_contracts.md
  • explicit portfolio snapshot contract:
  • types.ts: src/app/domain/portfolio/types.ts
  • explicit prediction-history contract:
  • types.ts: src/app/domain/prediction-history/types.ts
  • runtime saved-simulation repository:
  • repository.ts: src/app/domain/persistence/repository.ts
  • runtime saved-simulation service:
  • service.ts: src/app/domain/persistence/service.ts
  • runtime prediction-history repository and service:
  • repository.ts: src/app/domain/prediction-history/repository.ts
  • service.ts: src/app/domain/prediction-history/service.ts

5.3 Source of Truth for Strategy Families

5.4 Source of Truth for UI State

  • application store:
  • useCalculatorStore.ts: src/app/store/useCalculatorStore.ts
  • persistence.ts: src/app/store/persistence.ts
  • types.ts: src/app/store/types.ts
  • responsibility split:
  • calculator session history belongs to the store
  • durable saved simulations belong to the persistence repository/service layer
  • product composition:
  • App.tsx: src/app/App.tsx

5.5 Update Rule

For every product behavior change, assess whether you need to update:

  • this specification
  • the product roadmap document
  • the technical documentation for the relevant family
  • the documentation for the specific bond
  • UI copy and tooltips

5.6 Source of Truth for the Current Product State

If this document, the UI, and technical documentation seem inconsistent, use this order of verification:

  1. this document defines the product requirement
  2. the roadmap document defines the sequencing and scope of future stages
  3. technical documentation defines the intended implementation
  4. code and tests show the current actual state

If points 1 or 2 do not match points 3 and 4, treat that as debt to clarify, not as default product behavior.

6. Product Decisions Currently in Force

These are binding decisions right now. They must not be changed unintentionally in future iterations.

6.1 The Final Investment Assessment Is Interpreted Through the Last Year

  • the user may analyze the investment path in intermediate years
  • the calculator simulates the real progression of the investment, so the final assessment for a horizon of X years should be based on the last year in the yearly table and the final results
  • reason: taxes and costs are not always realized immediately

6.2 Family Bonds Are Filtered by Eligibility, Not by the Engine

  • ROS and ROD depend on 800+
  • the selection rule belongs to the selection layer, not the simulation layer
  • at this stage the calculator intentionally does not yet enforce the purchase amount cap resulting from the amount of received benefits

6.3 Account Type Is Disabled for Now

  • Brokerage account / IKE / IKZE is visible in the product
  • switching is disabled
  • it does not affect the calculator result

6.4 Gross and Net Value Have Fixed Semantics

  • Gross value = portfolio value before taxes and costs already realized up to a given moment
  • Net value = portfolio value after taxes and costs already realized
  • in the last year Net value means the final settlement result
  • intermediate years primarily show the progression of the investment and the portfolio while it is still running, not yet a separate unified mode answering the question: how much would I get if I ended the investment in exactly this year

6.5 The Product Is Not Yet an Investment Portfolio

  • the current version is a comparison calculator
  • the roadmap and data layer are intended to prepare the ground for a portfolio, but the portfolio is not in the current scope

7. User Groups

7.1 Primary User

An individual who:

  • wants to compare retail treasury bonds
  • knows basic financial concepts but does not want to calculate everything manually
  • needs a simple, readable comparison

7.2 Advanced User

Someone who:

  • deliberately compares different inflation scenarios
  • pays attention to tax, reinvestment, and redemption
  • wants to analyze results year by year

7.3 Future User

Someone who could later:

  • manage a bond portfolio
  • track specific bond issues
  • update the investment state over time
  • compare a historical purchase with the current portfolio state
  • launch the calculator through dialogue with an assistant instead of manually filling the whole form

8. Product Screens and Their Responsibilities

8.1 Calculator

Status: Implemented

Responsibility:

  • enable full bond comparison without leaving the application
  • collect user input data
  • show the final result and the path of the investment

Contains:

  • bond selection
  • investment parameters
  • comparison chart
  • results summary
  • detailed yearly table

8.2 How the Calculator Works

Status: Implemented

Responsibility:

  • explain to the user how to use the application
  • reduce the risk of incorrect metric interpretation

8.3 Product Roadmap

Status: Implemented

Responsibility:

  • show the product development direction
  • place the current calculator within the broader vision

8.4 Calculator Input Assistant

Status: Planned

Responsibility:

  • guide the user through questions about investment parameters
  • fill the form for the user based on their answers
  • run the same simulation used by manual mode
  • hand back a ready form state and result, with the option for further manual adjustment

9. Diagrams and Visual Materials

This section should shorten onboarding into the product. Mermaid diagrams show logic and responsibility boundaries, and screenshot placeholders define which UI captures are worth adding to the documentation.

9.1 Product Flow Diagram

flowchart LR
    A[User sets parameters] --> B[Selection layer]
    B --> C[Selection of allowed bonds]
    C --> D[Simulation engine]
    D --> E[Yearly results]
    D --> F[Final results]
    E --> G[Chart and yearly table]
    F --> H[Summary and ranking]
    G --> I[Interpretation in UI]
    H --> I

Purpose of the diagram:

  • show the path from user input to results
  • separate instrument selection from simulation itself
  • help a new person understand where product logic ends and presentation begins

9.2 Diagram of Layer Responsibility Boundaries

flowchart TB
    subgraph Selection[Selection layer]
        S1[Eligibility]
        S2[Selection sanitization]
        S3[800+ rules]
    end

    subgraph Engine[Engine layer]
        E1[Bond strategies]
        E2[Taxes and redemption]
        E3[Reinvestment]
        E4[Yearly and final results]
    end

    subgraph UI[UI layer]
        U1[Form]
        U2[Chart]
        U3[Summary]
        U4[Yearly table]
        U5[In-app documentation]
    end

    Selection --> Engine
    Engine --> UI

Purpose of the diagram:

  • reinforce the boundary selection -> engine -> UI
  • reduce the risk of putting eligibility rules into the engine
  • help during handoff and change review

9.3 Result Interpretation Diagram

flowchart TD
    A[User looks at year N] --> B{Is it the last year of the horizon?}
    B -- Yes --> C[Treat it as the final settlement result]
    B -- No --> D[Treat it as the investment in progress]
    D --> E[Useful for understanding the path]
    D --> F[Not always equal to the question of how much I get if I close the investment]
    C --> G[This is the main basis for the final decision]

Purpose of the diagram:

  • reinforce the most important product interpretation rule
  • distinguish intermediate years from the last year
  • limit the risk of misreading tables and the chart

9.4 800+ Logic Diagram

flowchart TD
    A[Did the user select 800+?] --> B{Yes or no}
    B -- Yes --> C[ROS and ROD are available in selection]
    B -- No --> D[ROS and ROD are unavailable]
    C --> E[The engine calculates them like other family bonds]
    E --> F[At the current stage there is no enforcement of the benefit amount cap]

Purpose of the diagram:

  • clearly show the current product state
  • emphasize that the current stage intentionally does not implement the 800+ amount cap
  • separate availability in the UI from simulation logic

9.5 Roadmap and Stage Dependency Diagram

flowchart LR
    P0[Stage 0\nFinalize MVP logic] --> P1[Stage 1\nData automation]
    P1 --> P2[Stage 2\nDatabase and saved simulations]
    P2 --> P3[Stage 3\nInflation model]
    P3 --> P4[Stage 4\nMin/max scenarios]
    P3 --> P5[Stage 5\nVolatility simulator]
    P2 --> P6[Stage 6\nRecurring investing and IKE/IKZE]
    P3 --> P6
    P4 --> P6
    P5 --> P6
    P6 --> P7[Stage 7\nInput assistant]

Purpose of the diagram:

  • show the order of product development
  • explain dependencies between data, prediction, and the future portfolio, including the fact that Stage 4 and Stage 5 are optional extensions after Stage 3
  • help PMs and developers plan scope

9.6 Screenshot Placeholders to Be Completed

Screen 1. Main Calculator Entry

Placeholder: TODO_SCREEN_01_MAIN_CALCULATOR_ENTRY

The screen should capture:

  • the full top area of the calculator in desktop view
  • the investment-parameter form
  • the bond-selection section
  • the visible 800+ selected state
  • the visible disabled IKE / IKZE selection state
  • at least a few selected bonds, including one family bond and one standard bond

Purpose of the screen:

  • show the user's entry point
  • show which parameters are actually active
  • show that some functions are visible but not yet active

Screen 2. Chart and Results Summary

Placeholder: TODO_SCREEN_02_RESULTS_OVERVIEW

The screen should capture:

  • the comparison chart with at least three bonds
  • one specific active metric, ideally Net value or Real profit
  • the results summary directly below or next to the chart
  • a visible difference between the trend section and the final ranking section

Purpose of the screen:

  • show that the chart and summary serve different roles
  • help the reader understand where to look for the trend and where to look for the final result

Screen 3. Detailed Yearly Table

Placeholder: TODO_SCREEN_03_YEARLY_TABLE

The screen should capture:

  • the yearly table in desktop view
  • a visible Single bond / Comparison view switch
  • several active columns, including Gross value, Net value, Taxes, or Costs
  • the visible last year and at least one intermediate year
  • if possible, a row with redemption or a moment of significant state change
  • if possible, a visible Early redemption or Full redemption status

Purpose of the screen:

  • show how the user analyzes the investment year by year
  • show that the same section also supports year-by-year comparison across multiple bonds
  • support the explanation that intermediate years are not the same as final settlement

Screen 4. How the Calculator Works Page

Placeholder: TODO_SCREEN_04_HOW_IT_WORKS

The screen should capture:

  • the top part of the page with the most important result-interpretation rule
  • a section explaining metrics or result views
  • a visible warning that the final investment assessment should be based on the last year

Purpose of the screen:

  • show that the product includes an educational layer inside the app
  • document how limitations and result semantics are communicated

Screen 5. Product Roadmap Page

Placeholder: TODO_SCREEN_05_PRODUCT_ROADMAP

The screen should capture:

  • at least the first 2-3 roadmap stages
  • a visible Stage 0
  • visible dependencies between MVP closure, data automation, and further product expansion

Purpose of the screen:

  • show the current development direction
  • support handoff between work on the current calculator and future stages

9.7 Rule for Maintaining Visual Materials

  • Mermaid diagrams should be updated together with changes to product logic or roadmap
  • screenshots should be refreshed when the screen structure, result interpretation, or limitation messaging changes
  • final screenshot files should go to the docs/assets/product-spec/ directory
  • the screenshot file name should correspond to the placeholder name, for example TODO_SCREEN_01_MAIN_CALCULATOR_ENTRY -> docs/assets/product-spec/screen_01_main_calculator_entry.png
  • after a real screenshot is added, the placeholder in the text should be replaced with a file link
  • if the text document and visual material diverge, treat it as documentation debt that must be closed

10. Main User Flows

10.1 Comparing Several Bonds

  1. The user selects bonds to compare.
  2. They set the investment parameters.
  3. They analyze the chart and results summary.
  4. For the final decision, they look at the result from the last year of the investment horizon.

10.2 Analyzing One Bond Year by Year

  1. The user selects a bond.
  2. They go to the detailed yearly table.
  3. They check year by year when taxes are recognized, when redemption appears, and how net value changes.

10.2a Comparing Multiple Bonds Year by Year

  1. The user switches the table to Comparison view.
  2. They choose which data points should remain visible.
  3. They switch grouping to Bonds or Metrics.
  4. They compare yearly progressions of several bonds in a single table without leaving the results screen.

10.3 Understanding Product Logic

  1. The user opens the How the calculator works page.
  2. They read the description of parameters, metrics, and interpretation.
  3. They return to the calculator with a better understanding of the result.

10.4 Future Flow: Entry Through the Assistant

  1. At entry, the user chooses whether to use the assistant.
  2. The assistant asks questions about investment parameters, such as starting amount, recurring contributions, horizon, 800+, and account type.
  3. The assistant maps the answers to the form state.
  4. The calculator runs the standard simulation using the same rules as manual mode.
  5. The user gets a ready result and can manually adjust the form before recalculating.

11. Input Parameters and Their Meaning

11.1 Investment Amount

Status: Implemented

  • affects the number of bonds purchased
  • affects the moment of purchasing additional bonds from interest or cash

11.2 Investment Horizon

Status: Implemented

  • determines the simulation length
  • affects whether a bond reaches natural maturity or ends in early settlement
  • is critical for interpreting the final result

11.3 Inflation

Status: Implemented

  • affects inflation-indexed bonds
  • affects real value and real profit

11.4 NBP Reference Rate

Status: Implemented

  • affects variable-rate bonds

11.5 800+

Status: Implemented

  • unlocks family bonds ROS and ROD
  • does not change simulation logic for other bonds
  • at this stage the calculator intentionally does not yet support the purchase amount cap resulting from the amount of received 800+ benefits

11.6 Account Type

Status: Implemented / disabled

  • currently informational only
  • prepared for future IKE / IKZE logic

12. Rules for Presenting and Interpreting Results

12.1 Gross Value

Portfolio value before taxes and costs already realized up to a given moment.

12.2 Net Value

Portfolio value after taxes and costs already realized. In the last year, it means the final settlement result.

12.3 Net Profit

The difference between net value and the invested amount.

12.4 Real Profit

Net profit after accounting for inflation.

12.5 The Most Important Interpretation Rule

If the user analyzes an investment over X years, they should ultimately look at the result from the last year because:

  • earlier years show the investment path
  • some taxes and costs may only be realized at the end

Earlier years are important for understanding the progression of the investment, but they are not always the final settlement outcome for a given year.

The scenario in which the product shows a separate comparison result for the question “how much would I get if I ended the investment in each subsequent year” is now implemented as an explicitly selectable global analytical model. It is still not an implicit promise of the default yearly-result semantics, but a consciously selected interpretation layer.

12.6 The Current Product Has a Narrow Close the Investment in Year X Mode

The current version of the product:

  • shows the yearly investment path according to the mechanics of a given bond
  • shows the final settlement in the last year of the adopted horizon
  • exposes a global Year-by-year liquidation interpretation mode
  • applies the active interpretation consistently across chart, summary, and the detailed yearly table
  • keeps the default canonical result semantics separate from the explicitly selected analysis mode
  • treats any expansion of that mode to other product sections as a separate roadmap topic rather than a hidden semantic of all current views

13. Functional Requirements

13.1 Bond Selection

Status: Implemented

The product must allow:

  • selection of multiple bonds at once
  • logical control of family bond availability
  • presentation of bonds in two views
  • the conscious limitation of the current stage: 800+ controls ROS / ROD availability, but does not yet enforce the purchase amount cap resulting from benefit amount
  • in the future, also support choosing and configuring assistant-based entry, which ends in the same form state

13.2 Simulation

Status: Implemented

The product must:

  • calculate results for all supported bonds
  • account for different interest accrual mechanisms
  • account for taxes, redemption, and reinvestment

13.3 Results

Status: Implemented

The product must:

  • show the final result
  • show the year-by-year path
  • allow comparison of multiple bonds inside the yearly table
  • allow changing the visible data set in the yearly table
  • show redemption status in a way that distinguishes natural redemption from early redemption
  • allow column filtering
  • allow result interpretation without knowledge of engine implementation
  • clearly distinguish the investment path over time from final settlement for the selected horizon

13.3a Global Analysis Mode for Results

Status: Implemented

The product must provide one global result-analysis mode state that the UI may expose through more than one control point.

Mandatory requirements:

  • the switch must control one shared application-level state value
  • the active analysis mode must affect, consistently:
  • the comparison chart
  • the results summary
  • the detailed yearly table
  • local result components must not keep their own competing interpretation semantics
  • the product may expose more than one UI control for that same global state as long as they do not create competing sources of truth

Supported modes:

  • Investment progression
  • Year-by-year liquidation

UI placement requirements:

  • in the current product there is no single large control panel above the result sections
  • the global analysisMode state is controlled through two small UI switches:
  • in the Comparison chart section
  • in the Detailed yearly table section
  • both switches must control exactly the same global state
  • the Results summary section must reflect the active mode, but it does not have to expose its own switch
  • descriptive section headers should not repeat the active mode in full sentence form when the same context is already visible through a badge or a switch

Result-section responsibility table:

Section Has its own switch? Shows the active mode? Reacts to global analysisMode?
Comparison chart Yes Yes Yes
Results summary No Yes Yes
Detailed yearly table Yes Yes Yes

Control flow diagram:

This diagram shows the product-level UI behavior and the relationship between control points and result sections.

flowchart LR
    A[Switch in Chart] --> C[Global analysisMode state]
    B[Switch in Yearly Table] --> C
    C --> D[Comparison Chart]
    C --> E[Results Summary]
    C --> F[Detailed Yearly Table]

Semantic requirements:

  • Investment progression means the real investment path according to product mechanics and remains the default interpretation of the canonical result
  • Year-by-year liquidation means comparing the outcome under the assumption that the investment is ended in each subsequent year of its lifetime
  • both modes must be explicitly named in the UI
  • both modes must be treated as alternative interpretations of the same input data, not as two independent calculators
  • multiple UI entry points are allowed only as interfaces to the same shared global state

13.3b Implementation Requirements for the Year-by-year liquidation Model

Status: Implemented

This section is the binding developer specification.

The Year-by-year liquidation model must work as follows:

  1. it accepts the same investment input parameters used to build the canonical result
  2. for every year X from 1 to the full investment horizon it creates a separate parameter set with the horizon shortened to X
  3. for each such horizon it runs a full recalculation through the bond engine
  4. from each recalculation it takes the final result for that horizon
  5. it assembles those final results into the yearly row series of the analytical model

Flow diagram:

flowchart TD
    A[Input: params and canonical context] --> B{Year X from 1 to N}
    B --> C[Create params with horizon = X]
    C --> D[Run full bond-engine recalculation]
    D --> E[Read final result for year X]
    E --> F[Append row to YearByYearLiquidationAnalysis]
    F --> B
    B -->|after loop ends| G[Return completed analysis model]

Mandatory requirements:

  • the model must not interpret intermediate investment_progression rows as the final liquidation answer for year X
  • the model must not add interpretation-specific fields directly to the canonical result contract
  • the model must exist as a separate analysis model with its own output contract
  • the model must preserve a consistent meaning across all result sections using the active global analysis mode

Naming and semantic requirements:

  • liquidation-model fields must be explicitly distinguished from progression fields whenever the semantics are not identical
  • the developer must not reuse canonical-result names merely because the values look similar in a table

Performance and quality requirements:

  • the first implementation may use engine recalculation per year
  • if the feature is later expanded and becomes a performance hotspot, optimization must preserve the same semantics
  • no optimization may change the meaning of the model without updating this specification and the technical documentation

13.4 Documentation in the Product

Status: Implemented

The product should include:

  • a page explaining how the calculator works
  • a product roadmap page

13.5 IKE / IKZE

Status: Out of scope

Current rules:

  • the element is visible in the UI
  • partial tax logic must not be implemented without a full product decision
  • future implementation requires separate scope and acceptance criteria

13.6 Future Calculator Input Assistant

Status: Planned

The product should eventually allow:

  • launching the calculator in conversational mode
  • collecting input through a sequence of questions instead of manually filling all fields
  • support for both one-time and recurring investing
  • filling the same form used by manual mode
  • generating the exact same result as for the same data entered manually
  • switching from assistant mode to manual mode without losing data

14. Data Requirements

14.1 Current Data

Status: Implemented

The product uses the bond catalog as the source of truth for product parameters.

14.2 Dynamic Data in the Future

Status: Planned

The plan assumes automation of:

  • the reference rate
  • issuance terms
  • current inflation as the default input parameter

Inflation prediction belongs to a later stage of simulation model development, not to the basic automation of current data.

14.3 Role of the Scraper

Status: Planned

The scraper has two goals:

  1. update issuance parameters and data needed by the calculator
  2. start building the data layer for the future investment portfolio

This means the scraper should eventually collect data not only about bond types, but also about specific issues and their history.

14.4 Portfolio Direction

Status: Planned

The data layer should eventually make it possible to:

  • save historical issuance parameters
  • show a historical purchase in the portfolio
  • update the current investment state without losing historical context

15. Product Boundaries and Layer Responsibilities

This section is especially important for developers.

15.1 Selection Layer

Responsible for:

  • bond availability for current parameters
  • eligibility logic, such as 800+
  • sanitization of instrument selection

Not responsible for:

  • cash flow simulation
  • taxes
  • redemption

15.2 Bond Engine Layer

Responsible for:

  • financial logic
  • simulation events
  • yearly and final results

Not responsible for:

  • product eligibility
  • UI rules
  • future portfolio rules that are not yet part of scope

15.3 UI Layer

Responsible for:

  • correctly showing results
  • consistent filters, tooltips, and views
  • helping the user interpret the data
  • in the future, also for a consistent experience between manual input and assistant-based input

It should not change the meaning of metrics relative to the engine.

15.4 Analysis-Model Layer

Responsibilities:

  • build explicit interpretation models on top of the canonical result
  • separate the real investment progression from alternative analytical models
  • provide one defended semantic layer to view adapters

It must:

  • exist as a separate layer between the canonical result and view adapters
  • use explicit analytical-model identifiers
  • have separate contracts for models with genuinely different semantics

It must not:

  • move semantics into UI components
  • extend the canonical result with fields specific to a single interpretation
  • mix layout logic with analytical logic

15.5 Relationship Between the Canonical Result and Analysis Models

Binding rule:

  • the canonical result describes the real progression of the investment and remains the source of truth
  • analysis models describe how those data are interpreted or recomputed into a defended analytical model
  • view adapters prepare data for the chart, summary, and tables

The developer must assume that additional analysis models may appear later.

This means:

  • a new analysis model should be added as a separate module
  • adding a new model should not require corrupting the existing canonical result
  • UI components should consume data after the analysis-model / view-adapter layer rather than invent semantics locally

16. UX/UI Requirements

16.1 UX Priorities

  • the product should be readable for a non-technical user
  • financial data should be easy to interpret
  • the interface should explain product logic, not only show numbers

16.2 Visual Priorities

  • consistency across sections
  • consistent active and inactive states
  • clear information hierarchy
  • consistency between light and dark mode

16.3 Tables and Filters

Filters and toggles should be:

  • consistent across tables and charts
  • readable even in the inactive state
  • interpretable without guessing how they work

17. Non-Functional Requirements

17.1 Responsiveness

The product should work correctly on desktop and mobile devices.

17.2 Readability and Accessibility

The product should:

  • maintain readable contrast
  • present data unambiguously
  • minimize the risk of incorrect interpretation

17.3 Maintainability

Product changes should be possible without rewriting the whole engine.

17.4 Data Auditability

Every change in the data layer should go through validation and be auditable.

18. Product Roadmap

Stage 0. Finalize Business Logic and UI for the MVP

Status: Planned

Goal:

  • close business and interpretation decisions before the product begins broader data automation and scenario expansion

Scope:

  • describe the current calculation model and verify behavior for all bond families
  • decide whether the product primarily shows the real investment state year by year or a separate unified comparison model
  • clarify rules for interpreting taxes, costs, and final settlement in the UI
  • explicitly describe items postponed beyond the MVP, for example the 800+ amount cap and IKE / IKZE logic

Stage 1. Automation of Market and Issuance Data

Status: Planned

Goal:

  • reduce manual data maintenance

Scope:

  • automatic reference rate
  • automatic retrieval of current inflation as the default input parameter
  • scraper for issuance terms
  • validation and catalog update pipeline

Stage 2. Database Foundation for the Future Bond Portfolio

Status: Planned

Goal:

  • prepare the data layer for issuance history and the future user portfolio

Scope:

  • data about specific issues
  • history of issuance parameters
  • data model for purchase history and current investment state
  • data model for saved calculations and user-saved simulations
  • data model for saving inflation predictions, prediction source, fetch date, and later comparison with actual inflation

Stage 3. Expansion of the Inflation Model

Status: Planned

Goal:

  • move from manual inflation to a more trustworthy prediction

Scope:

  • external inflation prediction
  • separation of manual and default inflation
  • save the inflation prediction used for a simulation into the data layer prepared in Stage 2
  • the ability to later compare an old prediction with actual inflation

Stage 4. Min / Max Scenarios

Status: Planned

Goal:

  • show the user a range of outcomes, not just one variant

Scope:

  • minimum scenario
  • maximum scenario
  • range presentation in the UI

Stage 5. Inflation Volatility Simulator

Status: Planned

Priority: Low

Goal:

  • add a more realistic model of inflation fluctuations

Scope:

  • inflation paths
  • accounting for historical volatility
  • presenting a distribution or range of results

Stage 6. Recurring Investing + IKE / IKZE

Status: Planned

Goal:

  • evolve the product from a one-time investment calculator to a recurring-investment model

Scope:

  • regular contributions
  • IKE / IKZE logic
  • the impact of contribution schedule and account type on the result

Stage 7. Calculator Input Assistant

Status: Planned

Goal:

  • allow the user to prepare a complete simulation through dialogue instead of manual form completion

Scope:

  • a start question asking whether the user wants to use the assistant
  • a sequence of questions about investment parameters, such as starting amount, recurring contributions, contribution frequency, investment horizon, 800+, and account type
  • support both one-time and recurring investment situations
  • map answers to the same form state used by the manual mode
  • run the same simulation and the same engine as the manual calculator
  • allow the user to switch to manual form editing after the dialogue ends

19. Dependencies and Risks

19.1 Dependencies

  • external data for the reference rate
  • source of data for issuance terms
  • future source of inflation prediction
  • target data model for the portfolio

19.2 Product Risks

  • user misinterpretation of results
  • lack of consistency between product logic and UI communication
  • scope sprawl when combining the calculator with the future portfolio
  • implicitly treating the 800+ limitation as fully implemented, even though the current stage intentionally does not enforce the purchase amount cap

19.3 Delivery Risks

  • drift between product and technical documentation
  • partial implementation of future functions without full PM decisions
  • changes in the data layer without a full validation and update plan

20. Acceptance Criteria

20.1 Calculator

The state is accepted when:

  • the user can calculate results for all supported bonds
  • the final result is consistent between the chart, summary, and yearly table
  • the user can compare several bonds without knowing the engine implementation

20.2 Result Interpretation

The state is accepted when:

  • the user understands the meaning of Gross value, Net value, Net profit, and Real profit
  • UI communication does not contradict engine semantics
  • in-app documentation explains why the final assessment should be based on the last year
  • product documentation clearly distinguishes the default investment progression from the explicit global close the investment in year X analysis mode
  • the Year-by-year liquidation model is implemented as a separate analysis model rather than as a reinterpretation of intermediate progression rows
  • chart, summary, and yearly table all react to the same active global analysis mode

20.3 UI and Interactions

The state is accepted when:

  • filters and toggles are visually and logically consistent
  • tables and summary use the same metric meanings
  • unavailable or postponed elements are clearly marked
  • the global analysis-mode switch is placed above the result sections and clearly communicates that it changes the interpretation of the whole result set

20.4 Every Subsequent Roadmap Stage

Each stage is considered ready only when:

  • it has its own closed scope
  • it includes updates to product and technical documentation
  • it has tests
  • it does not break the current calculator function

20.5 Minimum Evidence Pack for Work Acceptance

When handing off changes, the developer should provide:

  • information about which requirement or section of this specification was changed
  • information about which technical documents were updated
  • information about which tests confirm the change
  • information about whether user-facing behavior changed or only the implementation

21. How to Use This Specification During Handoff

21.1 If You Are Taking Over the Project

First:

  1. read the sections Implementation status and scope map, Source-of-truth map, and Product decisions currently in force
  2. identify the area you are changing
  3. open the relevant technical document from the Related documents section
  4. only then inspect the implementation

21.2 If You Are Changing Product Scope

You must assess whether the change requires updating:

  • this specification
  • the roadmap
  • in-app documentation
  • family or bond technical documents

21.3 If You Are Changing Already Implemented Behavior

You must explicitly state:

  • whether the product requirement is changing
  • whether only the implementation is changing
  • whether the UI communication is changing

21.4 Checklist Before Closing a Task

Before closing a task, check:

  • whether the scope status in this specification is still correct
  • whether the UI communicates anything different from the engine
  • whether technical documentation was updated where needed
  • whether a partially active function currently marked as Out of scope was introduced

21.5 Document Versioning Rule

For every meaningful product change:

  • update the last review field
  • if the meaning of requirements or scope changes, bump the document version
  • if only the wording is clarified, keep the version and describe the change in the PR or commit

22. Open Questions

  • which source of inflation prediction should be the default
  • how often the scraper should update data
  • whether the future portfolio should be local or backend-based
  • how historical issues should be presented to the user
  • when and to what extent the IKE / IKZE logic should be activated
  • when and how the amount-cap control for family bonds ROS / ROD should be enabled

23. Related Documents

Technical documents related to this specification:

Final Note

This specification should remain consistent with:

  • the current UI
  • technical documentation
  • the roadmap
  • data and architecture assumptions

Its value lies not only in describing the product, but in making it possible to take over work in the middle of the project without reconstructing the state from commits and conversations.