MacroLens

Professional macro trading terminal for regime analysis, Fed policy, yield curves, inflation, cross-asset confirmation, Forecast Lab diagnostics, and report-ready market intelligence.

Live app · Deploy · User guide

Production: web Vercel · API Hugging Face Spaces · DB Supabase Postgres

MacroLens combines economic indicators, Fed policy, yield curve dynamics, inflation, market breadth, cross-asset signals, AI-assisted context, and Forecast Lab model artifacts into a signal-first dashboard for macro trading decisions.

Screenshots

Add screenshots under each heading after capturing the current UI.

Dashboard

Radar

Macro Sentiment

Fed Policy

Yield Curve

Inflation

Analysis: Relative Performance

Forecast Lab

Calendar

What MacroLens Does

Layer	Purpose	Primary Pages
Macro cycle	Tracks growth, recession, and business-cycle pressure across indicator groups	Dashboard, Radar, Macro Sentiment
Fed policy	Scores policy stance using rates, neutral-rate context, direction, FOMC probabilities, and balance sheet	Dashboard, Fed Policy
Yield curve	Monitors spread inversion, curve momentum, tenor snapshots, percentiles, and curve-pattern signals	Dashboard, Yield Curve, Radar
Inflation	Tracks CPI, PCE, PPI, breakevens, expectations, and component contribution	Inflation, Dashboard
Market confirmation	Confirms macro regimes with relative performance, breadth, indices, Bitcoin, and cross-asset behavior	Analysis, Dashboard
Forecast Lab	Displays trained phase models, macro forecasts, ensemble evidence, stress diagnostics, and feature importances	Forecast Lab
Workflow outputs	Supports macro briefings, event review, report previews, and printable dashboards	Calendar, Reports

The core decision model is the Trading Navigator: a regime matrix that combines macro sentiment and Fed policy into allocation, factor, sector, geography, and trading-idea context.

Key Features

Dashboard And Navigator

Active macro regime and navigator quadrant
Fed policy score, macro sentiment score, recession probability, and yield curve snapshot
Cross-asset confirmation from risk, dollar, commodities, volatility, and curve signals
Allocation summary across equities, bonds, commodities, cash, and gold
Factor tilts, sector allocation, geography bias, and trading ideas

Radar

Cycle score and recession probability panels
Recession checklist and historical recession bands
Cycle-score and recession-probability timelines
Tables for recession model evidence and signal-level context

Macro Sentiment

Leading, coincident, lagging, and inflation category views
Category-level macro scoring
KPI history and selected indicator details
Backend-backed loading, error, and empty states

Fed Policy

Policy score and stance interpretation
FOMC probabilities and rate-decision history
Rate path and dot-plot style views
Fed balance sheet and balance metrics
AI/context card when optional agent services are configured

Yield Curve

Treasury tenor snapshot
2Y10Y and related spread history
Curve momentum and percentile tables
Curve dynamics and pattern interpretation
SOFR/EFFR context where available

Inflation

CPI, Core CPI, PCE, Core PCE, PPI, Core PPI
Breakevens and expectations
Single-line, dual-line, and component-contribution charts
Component breakdown for current inflation pressure

Analysis

Relative Performance: sector, currency, and sentiment-relative charts
Major Indices & Bitcoin: index trend context, Bitcoin, dominance, and breadth overlays
Market Breadth: participation, highs/lows, moving-average breadth, and internal market health
Macro Overview: macro ratios and cross-check charts for liquidity, inflation, spreads, and leading indicators

Forecast Lab

Phase probability and ensemble dashboard
Macro forecasts by series and horizon
Stress bands and top z-score contributors
Feature importance and trained artifact metadata
Historical regime alignment and model diagnostics

Calendar And Reports

Briefings, economic calendar, events explorer, FOMC minutes, and news views
Report hub and print/preview-oriented report layouts
Compatibility redirects from /next/* to production routes

Requirements

Docker and Docker Compose for the recommended full-stack setup
Python 3.12 for backend container parity, or Python 3.11+ for local development
Node.js 20+ for frontend local development
FRED API key for full macro data ingestion
Network access for external macro and market data sources
RAM 4GB+ recommended; more is useful for Forecast Lab training and large artifacts

Project Structure

macrolens/
  backend/
    app/
      api/             FastAPI routers
      models/          SQLAlchemy ORM models
      schemas/         Pydantic schemas
      services/        Data, analytics, Forecast Lab, agents, market logic
      tasks/           Scheduler setup
    config/            Forecast Lab and navigator configuration
    data/              Runtime data and Forecast Lab artifacts
    tests/             Pytest suite
    Dockerfile
    requirements.txt

  frontend/
    src/
      app/             Next.js routes
      components/      Shared UI and dashboard screens
      features/        Feature-level hooks, components, utilities
      lib/             API client and shared utilities
      types/           Shared TypeScript contracts
    Dockerfile
    package.json

  USER_GUIDE.md        End-user workflows and page guide
  DEPLOY.md            Production deployment runbook
  docker-compose.yml   PostgreSQL + Redis + backend + frontend

Run With Docker

Copy the environment template first:

Copy-Item .env.example .env

Set at least FRED_API_KEY in .env for full macro ingestion.

Start the stack:

docker compose up --build

Open:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
Health check: http://localhost:8000/api/health
PostgreSQL: localhost:5432
Redis: localhost:6379

If the project was moved and Docker bind mounts resolve incorrectly, set PROJECT_ROOT in .env.

Run Locally

Backend

Start PostgreSQL and Redis yourself, or run them through Docker Compose.

cd backend
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
Copy-Item .env.example .env
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend

cd frontend
npm install
npm run dev

Open http://localhost:3000. The frontend proxies /api/* requests to the backend.

Production Deployment

MacroLens deploys as two pieces, because the backend is always-on (a background scheduler refreshes data and ML models train in-process) and therefore is not serverless:

Component	Host (free tier)
Frontend (Next.js)	Vercel
Backend (FastAPI)	Hugging Face Spaces (Docker)
Postgres	Supabase / Neon
Redis	Upstash

The Next.js frontend proxies /api/* to the backend (BACKEND_URL), so the browser stays same-origin and CORS is a non-issue on the happy path. For prod, set CORS_ALLOW_ORIGINS on the backend to your Vercel URL as defense-in-depth.

Full step-by-step runbook (including the all-in-one self-hosted Docker option) is in DEPLOY.md.

# Self-host the whole stack on one box:
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

Configuration

Main configuration is copied from .env.example into .env.

Variable	Purpose
`FRED_API_KEY`	FRED macro data access
`CORS_ALLOW_ORIGINS`	Comma-separated allowed origins (set to the frontend URL in prod)
`HISTORICAL_YEARS`	Rolling FRED/Yahoo history window
`FORECAST_LAB_DATE_FROM`	First month-end included in Forecast Lab training features
`FORECAST_LAB_LABEL_MODE`	Forecast Lab target mode: `rule_v1` or `asset_implied_v1`
`FORECAST_LAB_INCLUDE_DASHBOARD_CONTEXT`	Adds Navigator and Radar cross-checks to Forecast Lab summary
`ANTHROPIC_API_KEY`	Optional agent text generation
`OPENAI_API_KEY`	Optional memory embeddings
`MEMORY_EMBEDDING_BACKEND`	`auto`, `hash`, or `openai`
`TELEGRAM_INGESTION_ENABLED`	Optional Telegram ingestion toggle
`BACKEND_INTERNAL_URL`	Frontend rewrite target in Docker

When running the backend directly from backend/, copy backend/.env.example to backend/.env.

Data Sources

FRED: macro indicators, rates, yield curve data, inflation, and economic series
Yahoo-style market data: indices, ETFs, commodities, FX proxies, volatility, and cross-asset charts
CoinGecko: optional deeper crypto history with an API key
Anthropic: optional generation for agent/context cards
OpenAI: optional embeddings for memory retrieval
Telegram: optional news ingestion when configured

Testing And Code Quality

CI (.github/workflows/ci.yml) runs Ruff, Black, isort, Mypy, Pytest on Python 3.12 for the backend, plus lint / typecheck / build for the frontend. Backend tooling is configured in backend/pyproject.toml; coverage scope (Forecast Lab core, gate ≥ 60%) in backend/.coveragerc.

Backend:

cd backend
pip install -r requirements-dev.txt
ruff check app tests
black --check app tests
isort --check-only app tests
mypy app
pytest --cov=app/services/forecast_lab --cov-config=.coveragerc --cov-fail-under=60
pre-commit install   # optional: run black/isort/ruff on commit

Frontend:

cd frontend
npm run lint
npm run typecheck
npm run build

Current verification status:

Gate	Command	Status
Backend lint	`ruff check app tests`	Passing
Backend format	`black --check` / `isort --check-only`	Passing
Backend types	`mypy app`	Passing (129 files)
Backend tests	`pytest`	Passing: 29 tests
Backend coverage	Forecast Lab core	~68% (gate ≥ 60%)
Frontend lint / typecheck / build	`npm run …`	Passing

Documentation

USER_GUIDE.md: user workflows, page guide, data notes, and troubleshooting

Operational Notes

Forecast Lab output depends on active artifacts under backend/data/forecast_lab_artifacts.
Generated Forecast Lab artifacts can be large and should be handled deliberately.
Calendar pages include a mix of backend-backed and demo-backed views while ingestion matures.
/next/* routes are preserved as compatibility redirects to production routes.

License

Proprietary — Copyright (c) 2026 imnotkeril. All rights reserved. The source is publicly viewable for reference only; use, copying, modification, or redistribution is not permitted without written permission. See LICENSE.

Acknowledgments

MacroLens builds on:

FastAPI, SQLAlchemy, Pydantic, PostgreSQL, Redis
Next.js, React, TypeScript, Tailwind, React Query
Recharts, lightweight-charts, lucide-react
Pandas, NumPy, scikit-learn, XGBoost, hmmlearn
FRED, market data providers, and optional LLM/embedding providers

Name		Name	Last commit message	Last commit date
Latest commit History 38 Commits
.github/workflows		.github/workflows
backend		backend
frontend		frontend
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
DEPLOY.md		DEPLOY.md
LICENSE		LICENSE
README.md		README.md
USER_GUIDE.md		USER_GUIDE.md
compose-up.ps1		compose-up.ps1
docker-compose.prod.yml		docker-compose.prod.yml
docker-compose.yml		docker-compose.yml
llms.txt		llms.txt

Folders and files

Latest commit

History

Repository files navigation

MacroLens

Contents

Screenshots

Dashboard

Radar

Macro Sentiment

Fed Policy

Yield Curve

Inflation

Analysis: Relative Performance

Forecast Lab

Calendar

What MacroLens Does

Key Features

Dashboard And Navigator

Radar

Macro Sentiment

Fed Policy

Yield Curve

Inflation

Analysis

Forecast Lab

Calendar And Reports

Requirements

Project Structure

Run With Docker

Run Locally

Backend

Frontend

Production Deployment

Configuration

Data Sources

Testing And Code Quality

Documentation

Operational Notes

License

Acknowledgments

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages