Merge pull request #1 from Error404IsFound/tharun

[Tax][Iteration 1] Document existing transaction and dividend data model

project-docs/iteration-1/tax/transaction-dividend-data-model.md

@@ -0,0 +1,330 @@
+# Tax Metrics — Existing Transaction and Dividend Data Model
+
+**Owner:** Tharun Swaminathan
+**Iteration:** 1 — Design & Data Modelling
+**Date:** September 15, 2026
+
+## Objective
+
+The purpose of this review was to understand how Ghostfolio currently stores and
+handles transactions, especially dividend transactions, before adding any
+tax-related functionality.
+
+Since the tax feature will later include withholding tax, FIFO capital gains,
+average-cost calculations, tax lots, yearly summaries, and exports, it is
+important to first understand the existing data model instead of creating a
+separate structure that does not match the rest of Ghostfolio.
+
+No implementation changes were made as part of this task.
+
+## Current Persistence Model
+
+Ghostfolio stores portfolio transactions using the Prisma `Order` model in
+`prisma/schema.prisma`.
+
+Even though the database model is called `Order`, the rest of the application
+usually refers to these records as activities.
+
+The `Order` model already contains the main information needed to describe a
+portfolio transaction.
+
+| Field | Current purpose |
+|---|---|
+| `id` | Unique identifier for the activity |
+| `accountId` | Account associated with the activity |
+| `comment` | Optional user comment |
+| `createdAt` | Time the database record was created |
+| `currency` | Currency used by the activity |
+| `date` | Date of the financial activity |
+| `fee` | Fee associated with the activity |
+| `quantity` | Number of units or shares |
+| `symbolProfileId` | Asset associated with the activity |
+| `tags` | Tags attached to the activity |
+| `type` | Type of financial activity |
+| `unitPrice` | Price or value per unit |
+| `updatedAt` | Last time the record was updated |
+| `userId` | User who owns the activity |
+
+The currently supported activity types are:
+
+- `BUY`
+- `DIVIDEND`
+- `FEE`
+- `INTEREST`
+- `LIABILITY`
+- `SELL`
+
+This means the tax calculations should build on the existing activity model
+where possible instead of introducing a completely separate transaction model.
+
+## Dividend Representation
+
+Ghostfolio does not currently have a separate database table or entity just for
+dividends.
+
+A dividend is stored as a normal activity where:
+
+`type = DIVIDEND`
+
+The activity still uses fields such as `quantity`, `unitPrice`, `currency`,
+`date`, and `fee`.
+
+For example, one of the existing Ghostfolio import samples contains the
+following dividend activity:
+
+- Asset: Microsoft (`MSFT`)
+- Quantity: 5 shares
+- Unit price: 0.62 USD
+- Type: `DIVIDEND`
+- Fee: 0
+- Currency: USD
+- Date: November 17, 2021
+
+Using the existing quantity and unit-price values, the dividend amount
+represented by this activity is:
+
+`5 × 0.62 = 3.10 USD`
+
+This gives the tax feature a natural starting point for determining the dividend
+value. In the later withholding-tax design, this value can be used when defining
+the relationship between gross dividend, withholding tax, and net dividend.
+
+## Existing Fee Field
+
+Ghostfolio already has a `fee` field on the activity model.
+
+The same field is available when an activity is created, and the current DTO
+requires it to be a non-negative number.
+
+However, the current model does not define this field specifically as dividend
+withholding tax. It is a general activity fee.
+
+Because of this, the tax extension should not simply reinterpret `fee` as
+withholding tax.
+
+A brokerage fee and dividend withholding tax represent different pieces of
+financial information and may both exist on the same activity.
+
+For the later withholding-tax design, these values should remain conceptually
+separate:
+
+- Gross dividend
+- Activity fee
+- Withholding tax
+- Net dividend
+
+The exact withholding fields will be designed in the Sep 16 task. This review
+only establishes that the existing `fee` field should keep its current meaning.
+
+## API and DTO Flow
+
+The current Ghostfolio activity flow already provides a path that can be
+extended later for tax-related information.
+
+At a high level, the flow is:
+
+`Prisma Order` → `CreateOrderDto / UpdateOrderDto` → Activities backend service → Activity API response
+
+The existing `CreateOrderDto` already validates important transaction fields
+such as:
+
+- currency
+- date
+- fee
+- quantity
+- symbol
+- activity type
+- unit price
+
+The API activity interface then extends the stored `Order` with additional
+calculated information used by the application.
+
+This means the tax feature should reuse this existing flow where possible.
+Creating a second, independent dividend transaction API would add unnecessary
+duplication and make the system harder to maintain.
+
+## Currency Handling
+
+Currency is already part of Ghostfolio's activity model.
+
+The activity response also includes calculated values such as:
+
+- `feeInAssetProfileCurrency`
+- `feeInBaseCurrency`
+- `unitPriceInAssetProfileCurrency`
+- `value`
+- `valueInBaseCurrency`
+
+This is important for the tax feature because tax values may eventually need
+to be reported both in the activity currency and the user's base currency.
+
+Instead of creating a separate currency-conversion method only for tax, the
+future implementation should follow Ghostfolio's existing conversion approach
+where practical.
+
+The exact withholding-tax currency fields are not being decided in this task.
+That will be part of the Sep 16 schema design.
+
+## Transaction Ordering
+
+Transaction ordering is especially important for the later FIFO capital-gains
+calculation.
+
+During the code review, Ghostfolio's existing activity handling was found to
+use the activity date as the main chronological value.
+
+This gives us the primary ordering value needed for tax calculations:
+
+`activity date`
+
+However, FIFO also needs a deterministic rule when two transactions have the
+same date or timestamp.
+
+The activity model contains both an `id` and `createdAt`, but this review does
+not yet define which should be treated as the official secondary tax ordering.
+
+This should be explicitly decided in the FIFO specification rather than leaving
+the calculation dependent on accidental database ordering.
+
+For now, this is recorded as an open design question for the Sep 17 FIFO task.
+
+## Import Compatibility
+
+Ghostfolio already supports importing activities, including dividend
+transactions.
+
+This matters because future tax functionality cannot assume that every dividend
+was manually entered by the user.
+
+For example, an imported dividend may contain the basic dividend amount but may
+not contain withholding-tax information.
+
+The tax design should therefore be able to handle at least two situations:
+
+1. A dividend where withholding information is available.
+2. A dividend where withholding information is not available.
+
+Missing withholding information should not make an otherwise valid historical
+dividend unusable.
+
+The exact validation and default behavior will be defined when the withholding
+schema is designed.
+
+## Existing Tests
+
+Ghostfolio already contains tests and sample data involving dividend
+transactions.
+
+These are useful because future tax tests should follow the project's existing
+testing style instead of building a completely different testing approach.
+
+One useful example is
+`portfolio-calculator-msft-buy-with-dividend.spec.ts`, which already covers a
+Microsoft purchase together with a dividend. The existing import sample also
+contains an MSFT dividend activity.
+
+For future tax calculations, similar tests can be extended to verify exact
+numeric results for cases such as:
+
+- dividend withholding
+- multiple purchases followed by a sale
+- partial FIFO lot usage
+- multiple tax lots
+- same-date activities
+- rounding
+- missing withholding information
+
+No new tests were written during this task because Iteration 1 is currently
+focused on design and data modelling.
+
+## Design Conclusions
+
+Based on the existing Ghostfolio implementation, the tax feature should extend
+the current activity model rather than create a separate transaction system.
+
+The main conclusions from this review are:
+
+1. Dividends are already represented as normal activities using
+   `type = DIVIDEND`.
+
+2. The existing `Order` model provides most of the transaction information
+   needed by future tax calculations.
+
+3. The existing `fee` field should remain separate from withholding tax.
+
+4. Gross dividend, withholding amount, and net dividend should remain
+   distinguishable rather than being combined into one value.
+
+5. Existing currency-handling patterns should be reused where possible.
+
+6. Imported and historical dividends may not always contain withholding
+   information, so the future design needs to handle missing values safely.
+
+7. FIFO will need an explicitly documented ordering rule, especially when
+   multiple activities have the same date.
+
+These conclusions will be used as the starting point for the remaining tax
+design tasks in Iteration 1.
+
+## Open Questions
+
+The following questions were identified during this review and will be resolved
+in later Iteration 1 tax tasks.
+
+### Withholding Tax
+
+- Should the withholding amount be stored directly?
+- Should a withholding rate also be stored?
+- If both amount and rate are available, which one should be treated as the
+  source value?
+- Should withholding be optional for older or imported dividend records?
+- How should withholding amounts be represented across different currencies?
+
+### FIFO and Tax Lots
+
+- What secondary ordering rule should be used when activities share the same
+  timestamp?
+- How should stock splits affect tax-lot quantities and cost basis?
+- What information needs to be stored to trace a sale back to the acquisition
+  lots that were consumed?
+
+### Calculation Precision
+
+- Where should rounding occur?
+- Should calculations use the activity currency first and convert afterward,
+  or use base-currency values during the calculation?
+
+These questions are intentionally left open here because they belong to the
+specific design tasks scheduled later in Iteration 1.
+
+## Next Task
+
+The next tax task is scheduled for September 16:
+
+**Design the withholding-tax field schema for dividend transactions.**
+
+The Sep 15 review provides the baseline for that work.
+
+The next design will define the withholding-tax inputs and fields, including
+their types, optional/required behavior, validation rules, currency meaning,
+and relationship to gross and net dividend values.
+
+No withholding-tax implementation will be added yet because Iteration 1 is the
+design and data-modelling phase.
+
+## Relevant Files Reviewed
+
+The main Ghostfolio files reviewed for this task were:
+
+- `prisma/schema.prisma`
+- `libs/common/src/lib/dtos/create-order.dto.ts`
+- `libs/common/src/lib/interfaces/activities.interface.ts`
+- `apps/api/src/app/activities/activities.controller.ts`
+- `apps/api/src/app/activities/activities.service.ts`
+- `apps/api/src/app/portfolio/calculator/roai/portfolio-calculator.ts`
+- `apps/api/src/app/portfolio/calculator/roai/portfolio-calculator-msft-buy-with-dividend.spec.ts`
+- `test/import/ok/sample.json`
+
+These files were used to understand the current transaction and dividend data
+model, API flow, currency handling, and existing dividend behavior. No
+source-code changes were made during this review.