historical-prices/README.md

There are 2 projects combined in this program. 
First peogram : localhosr:5000/
Data Analysis & Signal Generation layer that happens before the simulation even begins.

Here is a summary of those specific capabilities:

1. Automated Pricing Retrieval
The program acts as a data bridge. Instead of you manually searching for prices, it can:

Fetch real-time or historical data for specific tickers (like SPY).

Maintain a local CSV database, ensuring you have a persistent record of price action to analyze without re-downloading everything every time.

2. EMA (Exponential Moving Average) Calculation
The program adds a layer of technical analysis to the raw prices:

It calculates the EMA (typically a 200-day or 50-day trend line).

Unlike a simple average, the EMA gives more weight to recent prices, making it more responsive to new market information.

3. Price/EMA Ratio Analysis
This is one of the program's most powerful analytical features. It generates a "Value Ratio" to help you understand market positioning:

The Math: It divides the current price by the EMA.

The Signal: * Ratio > 1.0: The asset is trading above its average (potentially overextended or in a strong uptrend).

Ratio < 1.0: The asset is trading below its average (potentially undervalued or in a downtrend).

Strategic Use: This ratio can be used to "tune" your DVA strategy—for example, investing more aggressively when the ratio is low and being more cautious when the ratio is high.

4. Tabular Data Export
All of this technical data—the raw price, the EMA, and the resulting Ratio—is organized into a clean, structured list. This allows you to:

See a "Heat Map" of when the asset was historically cheap or expensive relative to its trend.

Use these technical signals to justify the "Buy" or "Sell" recommendations the dashboard provides.
Summary of the "Technical Stack"CapabilityBenefitPrice FetchingSaves time on manual data entry.EMA CalculationIdentifies the long-term "fair value" trend.Price/EMA RatioQuantifies exactly how "expensive" or "cheap" the market is today.
Second Project ; localhost:5000/backtest 
a Dynamic Value Averaging (DVA) Backtester. Its primary purpose is to help investors simulate a sophisticated "Value Averaging" strategy to determine exactly how much they should buy or sell of an asset (like SPY) on a specific day of the month to stay on track with a financial goal.

Here is a summary of what the programs actually do:

1. Automated Strategy Simulation
The program takes a historical CSV file and "plays back" time.

It identifies a Monthly Anchor Day (e.g., the 27th of every month) and simulates making a trade on that exact day.

It calculates your Target Value Goal, which grows every month by a set amount (e.g., $500/month).

2. Intelligent "Buy/Sell" Recommendations
Instead of just buying a fixed amount (DCA), the program calculates the "Value Gap":

If the market is down: It tells you to Buy More to reach your target.

If the market is up: It tells you to Sell (or buy less) to lock in gains.

It calculates the exact number of units/shares you need to trade based on the most recent price in your data.

3. Real-Time Data Synchronization
The program is designed to handle "incomplete" months:

If today is the 28th but your anchor day is the 15th, the program doesn't just stop at the 15th.

It forces the latest available data point from your CSV to be processed, ensuring your "Next Recommended Move" is based on the most recent price (e.g., yesterday’s close).

4. Interactive Dashboard Reporting
Once the simulation runs, the program visualizes the health of your investment:

Target Value Goal: Where you should be according to your plan.

Total Invested: The actual cash you've put in out of pocket.

Current Portfolio Value: What your holdings are worth today.

Data Freshness: A badge that turns red if your CSV data is more than 5 days old.

Summary of the "User Flow"
Input: You provide a CSV of stock prices and a monthly investment goal.

Execution: The Python engine calculates the historical performance and the current gap.

Output: The Web Dashboard gives you a clear instruction: "Buy/Sell X units for $Y.YY."
1. Core Architecture OverviewThe project is split into three distinct layers that communicate in a linear pipeline.
A. The Data Engine (data_engine.py / CSV)This is the "Source of Truth."Role: Manages the ingestion of historical market data (e.g., SPY).Logic: It ensures the CSV is sorted chronologically and provides a path for the strategy engine to read price points.
B. The Strategy Engine (engine.py)This is the "Brain" of the program where the financial math happens.Data Slicing: Uses the Anchor Day logic to filter the CSV for specific monthly dates (e.g., the 27th of every month).Safety Net: Forces the inclusion of the absolute latest CSV row (e.g., 2026-01-27) to ensure the dashboard is never out of date.Simulation Loop: Iterates through dates, calculating:Target Value: (Monthly Increment $\times$ Month Number).Market Value: (Shares Owned $\times$ Current Price).The Move (va_diff): The gap between Target and Market value.JSON Serialization: Rounds all values and packages them into a history list of dictionaries to be sent to the frontend.
C. The Web Dashboard (backtest.html / JS)This is the "Interface" for the user.Controller (runSimulation): Triggers the Python logic via an API/Socket call and receives the history array.KPI Processor (updateKPIs): * Maps Python keys (like va_invested) to UI elements.Determines the Action Verb (Buy/Sell) based on the sign of va_diff.Updates the DOM with formatted currency strings.Integrity Checker (updateSyncBadge): Compares the data date to the current system date to warn the user if data is stale.

2. Key Data MappingsTo prevent the "Value = 0" issues we encountered, the architecture relies on strict key consistency:Python Key (Source)JavaScript VariableUI Element IDva_diffnextMoveAmountnextInvAmtva_investedtotalInvestedValuetotalSavedva_valuecurrentPortfolioValtotalValpricelatestPricelatestPriceDisplay

3. Data Flow SequenceTrigger: User clicks "Run Simulation" in the browser.Process: Python reads CSV $\rightarrow$ Filters by Anchor Day $\rightarrow$ Appends Latest Row $\rightarrow$ Calculates DVA Steps.Transmit: Python returns a JSON array of the simulation history.Render: JavaScript grabs the last element of that array to fill the KPI cards and uses the full array to draw the charts.