Segmentational Analysis

2026-06-02 04:58:07 -04:00
parent 341c816e61
commit 225b88ea4f
9 changed files with 237 additions and 179 deletions
@@ -0,0 +1,58 @@
+# Financial Screener & Personal Finance Assistant
+
+## Project Overview
+
+This project is a modular, rule-based financial analysis engine designed to evaluate assets and manage personal investment portfolios. It separates data acquisition, strategy configuration, and evaluation logic to provide actionable investment insights.
+
+---
+
+## Architecture Structure
+
+### 1. Data Pipeline (`/src/data/`)
+
+- **Fetcher:** Handles API communication (e.g., Yahoo Finance).
+- **Mapper:** Normalizes disparate API responses into a unified flat object structure.
+- **Asset Models (`/models/`):** Defines common properties for `Stock`, `Etf`, and `Bond`.
+
+### 2. Logic & Configuration (`/src/config/` & `/src/utils/`)
+
+- **`ScoringConfig.js`:** Houses all thresholds, gates, and weights.
+- **`RuleMerger.js`:** Dynamically applies sector-specific overrides to base rules.
+
+### 3. Evaluation & Personal Assistant (`/src/engine/` & `/src/assistant/`)
+
+- **`ScoringEngine.js`:** Orchestrates evaluation, applying market context and sector overrides.
+- **`PortfolioManager.js` (NEW):** Tracks individual holdings, cost basis, and performance metrics.
+- **`AdvisorModule.js` (NEW):** Provides personalized suggestions based on screening results and portfolio health.
+- **`EventMonitor.js` (NEW):** Tracks calendar events (Earnings Calls) to trigger alerts.
+
+---
+
+## Data Flow Diagram
+
+---
+
+## Future Enhancements
+
+### Phase 1: Core Engine & Soft Scoring
+
+- **Soft Scoring System:** Transition from "Hard Gates" to a weighted point-based system.
+- **Market Context Integration:** Automate the `marketContext` parameter by fetching real-time 10Y Treasury Yields.
+
+### Phase 2: Personal Finance Features
+
+- **Personal Portfolio Tracking:** Implement a `PortfolioManager` to track custom user holdings, monitor unrealized P&L, and calculate weightings relative to total assets.
+- **Automated Financial Coaching:** Develop an `AdvisorModule` that analyzes the portfolio and provides suggestions (e.g., "Reduce exposure to High-Debt REITs," or "Rebalance to increase Technology allocation").
+- **Earnings Call Notification System:** \* Integrate an earnings calendar API.
+  - Implement a polling or webhook service to monitor for upcoming calls.
+  - Add a notification service (Email, Push, or CLI log) to alert the user 24 hours prior to a scheduled earnings call.
+
+### Phase 3: Infrastructure & Intelligence
+
+- **Caching Layer:** Use local JSON caching to reduce API overhead.
+- **Sentiment Analysis:** Integrate news-scrapers to weight "Buy" signals based on recent headlines.
+- **Backtesting Module:** Run historical simulations to test strategy performance.
+
+---
+
+_Maintained by: AI Collaborator_