# 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_