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

2.6 KiB Raw Blame History