How hajinhyukson/faustcalc works
FaustCalc is an investment portfolio recommendation and reporting product. Investors enter holdings, preferences, and constraints in the browser; the Spring web API extracts profile/filter inputs, invokes the Python recommendation engine, and returns results for report generation and display. Separate branches support universe exploration, run history, dashboards, and methodology. The README documents the cross-service workflow; source-index references and excerpts support selected internal calls. Some unsampled service and pipeline wiring is therefore omitted rather than inferred.
Main entry points: api.ts Web API client · PortfolioController.java Portfolio API · PortfolioEngineService.java Engine bridge · cli.py Python CLI
Components 24
Browser experience
- Portfolio interview
java-web/webapp/src/pages/run/main.ts - Web API client
java-web/webapp/src/lib/api.ts - Universe explorer
java-web/webapp/src/pages/explore/main.ts - Run history
java-web/webapp/src/pages/history/main.ts - Report renderer
java-web/webapp/src/pages/report/render.ts
Web application
- Portfolio API
java-web/src/main/java/com/faustcalc/web/api/PortfolioController.java - Universe API
java-web/src/main/java/com/faustcalc/web/api/UniverseApiController.java - Dashboard API
java-web/src/main/java/com/faustcalc/web/api/DashboardApiController.java - Run history store
java-web/src/main/java/com/faustcalc/web/entity/PortfolioRunEntity.java - Preference extraction
java-web/src/main/java/com/faustcalc/web/service/PreferenceExtractionService.java - Preference filtering
java-web/src/main/java/com/faustcalc/web/service/FilterService.java - Investor profiling
java-web/src/main/java/com/faustcalc/web/service/InvestorProfileService.java - Engine bridge
java-web/src/main/java/com/faustcalc/web/service/PortfolioEngineService.java
Recommendation engine
- Python CLI
src/cli.py - Fit and allocation
src/ml/recommender.py - Portfolio risk
src/risk.py
Market data and features
- FMP market client
src/fmp_client.py - FMP market data
- Feature database
src/pipeline/db.py - Data refresh
src/pipeline/refresh_fundamentals.py
Reporting and analysis
- Narrative reports
java-web/src/main/java/com/faustcalc/web/service/GeminiReportService.java - Market analyses
src/analysis/theme_analysis.py - Gemini
Other components
- Investor
Connections 25
- Investor → Portfolio interview: enters holdings
- Portfolio interview → Web API client: submits run
java-web/webapp/src/pages/run/main.ts - Web API client → Portfolio API: HTTP requests
- Portfolio API → Preference extraction: extracts preferences
java-web/src/main/java/com/faustcalc/web/api/PortfolioController.java - Portfolio API → Preference filtering: filters candidates
java-web/src/main/java/com/faustcalc/web/api/PortfolioController.java - Portfolio API → Investor profiling: extracts profile
java-web/src/main/java/com/faustcalc/web/api/PortfolioController.java - Portfolio API → Engine bridge: runs engine
java-web/src/main/java/com/faustcalc/web/api/PortfolioController.java - Engine bridge → Python CLI: launches CLI
- Python CLI → Fit and allocation: dispatches recommendation
src/cli.py - Fit and allocation → Portfolio risk: uses risk metrics
src/ml/recommender.py - Fit and allocation → FMP market client: fetches market data
- FMP market client → FMP market data: requests prices
- Engine bridge → Narrative reports: generates narrative
- Narrative reports → Gemini: requests report
- Engine bridge → Report renderer: returns artifacts
java-web/src/main/java/com/faustcalc/web/service/PortfolioEngineService.java - Web API client → Report renderer: provides report data
- Universe explorer → Web API client: queries universe
java-web/webapp/src/pages/explore/main.ts - Web API client → Universe API: HTTP requests
- Dashboard API → Run history store: reads runs
java-web/src/main/java/com/faustcalc/web/api/DashboardApiController.java - Run history → Web API client: loads history
java-web/webapp/src/pages/history/main.ts - Web API client → Dashboard API: HTTP requests
- Universe API → Feature database: reads features
- Data refresh → FMP market client: fetches fundamentals
src/pipeline/refresh_fundamentals.py - Data refresh → Feature database: stores refreshed data
src/pipeline/refresh_fundamentals.py - Python CLI → Market analyses: runs analyses
src/cli.py