ATLAS TERMINAL
Personal Bloomberg Terminal β Institutional-Grade Financial Analysis for Everyone
---
## What is ATLAS Terminal?
ATLAS Terminal is a **full-stack financial analysis platform** that brings institutional-grade equity research tools to a single, unified interface. It combines **AI-driven qualitative analysis** of SEC 10-K filings with **quantitative valuation models**, real-time market data, and portfolio management β all wrapped in a sleek, dark-themed terminal UI.
**Design philosophy:** LLM for text interpretation, Python for numbers. This eliminates hallucination risk on financial figures while delivering nuanced qualitative insights from SEC filings.
---
## Pages & Features
### π Overview
Company snapshot at a glance β current price, sector, industry, market cap, P/E ratio, beta, dividend yield, 52-week range, **Altman Z-Score** (safe/grey/distress zones), and **DuPont decomposition** (ROE β NPM Γ Asset Turnover Γ Equity Multiplier).
### π¬ Research
AI-powered deep-dive analysis using Google Gemini. Ask natural-language questions about any company and receive structured financial insights with context from SEC filings, financial statements, and market data.
### π° Valuation β 5 Analytical Models
| Tab | Description |
|-----|-------------|
| **DCF Model** | 2-stage discounted cash flow with smart defaults from CAPM/Beta. Adjustable WACC, terminal growth, and FCF growth sliders. Analyst consensus (target price, recommendation) displayed alongside. |
| **Sensitivity** | WACC Γ Terminal Growth Rate matrix table. Center cell highlighted to show base-case intrinsic value. Instantly see how assumptions shift fair value. |
| **Monte Carlo** | 5,000-simulation DCF with randomized inputs. Histogram visualization (red below / green above current price). Statistics: mean, median, P10/P90, probability of upside. |
| **Tornado** | Variable impact ranking chart. Shows which input assumption (WACC, growth rate, terminal growth, margins) has the largest effect on valuation β sorted by sensitivity range. |
| **Reverse DCF** | Solves for the implied growth rate the market is pricing in. Compares market-implied growth vs. your assumption and analyst consensus. Uses scipy's Brent root-finding method. |
### π Technical Analysis
- **Candlestick chart** with volume histogram (TradingView Lightweight Charts)
- Period selector: 1MO, 3MO, 6MO, 1Y, 2Y
- **RSI(14)** with overbought/oversold classification
- **MACD** with signal line and histogram
- **Bollinger Bands** β %B, bandwidth, current position
- **Moving Averages** table β SMA/EMA 20/50/100/200 with ABOVE/BELOW signals
- **Fibonacci retracement** levels with "near current price" highlighting
- **ATR** (Average True Range) for volatility measurement
- **ADX** for trend strength detection
### π Financial Statements
Institutional-style financial data table with:
- **Income Statement**, **Balance Sheet**, **Cash Flow** tabs
- Up to 5 annual periods with proper date headers
- **YoY Growth** badges (green for positive, red for negative)
- **Margin %** rows (Gross Margin, Operating Margin, Net Margin)
- Row groups: Revenue, COGS, Gross Profit, SG&A, R&D, Operating Income, EBITDA, Net Income, EPS
- Pipe-separated multi-key lookup to handle both yfinance and yahooquery column naming conventions
### π
Earnings
- **Next earnings date** card with countdown
- **EPS Beat/Miss** visual history β green bars for beats, red for misses, with surprise percentage
- **Revenue & Earnings estimates** vs. actuals
- **Quarterly breakdown** cards
### π° News Feed
Split-view news aggregator:
- **Left panel**: Scrollable article list (40+ articles from Finviz & Google News) with source badges and timestamps
- **Right panel**: Article header bar + iframe embedding of original content
- "Open Original β" button for sites that block iframe embedding
- Ticker-specific filtering
### πΌ Portfolio
Position tracking with multi-currency support (USD, KRW, GBP, EUR, JPY, CNY). P&L calculation, FX-adjusted returns, and risk metrics including:
- **VaR** (Value at Risk)
- **Sharpe Ratio** & **Sortino Ratio**
- **Maximum Drawdown**
- **Beta** & **Correlation** to benchmark
### π SEC Filings (EDGAR)
Inline 10-K filing viewer:
- Downloads and parses latest 10-K from SEC EDGAR
- **5 section tabs**: Risk Factors (1A), MD&A (7), Financial Statements (8), Legal Proceedings (3), Controls & Procedures (9A)
- Intelligent content formatting β headers detected and styled, bullets indented, paragraphs separated
- **Word count** per section
- **AI Summary** button β sends section text to Gemini for key risk/trend extraction
- Section caching to avoid repeat downloads
### βοΈ Settings
- Google Gemini API key configuration
- SEC EDGAR email for fair-access compliance
- Persistent storage via localStorage
---
## Architecture
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β ATLAS TERMINAL β
ββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββ€
β Next.js 14 Frontend β FastAPI Backend β
β (Port 3000) β (Port 8000) β
β β β
β ββββββββββββββββββββ β ββββββββββββββββββββββββ β
β β App Router Pages β β β 13 API Routers β β
β β β’ Overview ββββββββββΆ β β’ /api/market β β
β β β’ Research β proxy β β’ /api/financials β β
β β β’ Valuation β /api/* β β’ /api/valuation β β
β β β’ Technical β β β β’ /api/technical β β
β β β’ Markets β β β β’ /api/earnings β β
β β β’ Earnings β β β β’ /api/edgar β β
β β β’ News β β β β’ /api/news β β
β β β’ Portfolio β β β β’ /api/portfolio β β
β β β’ Filings β β β β’ /api/insider β β
β β β’ Settings β β β β’ /api/analysis β β
β ββββββββββββββββββββ β β β’ /api/crypto β β
β β β β’ /api/fx β β
β ββββββββββββββββββββ β β β’ /api/estimates β β
β β Components β β ββββββββββββ¬ββββββββββββ β
β β β’ Sidebar β β β β
β β β’ Ticker Bar β β ββββββββββββΌββββββββββββ β
β β β’ Chat Panel β β β 15 Service Modules β β
β β β’ useTicker() β β β β’ dcf_engine β β
β ββββββββββββββββββββ β β β’ monte_carlo β β
β β β β’ sensitivity β β
β ββββββββββββββββββββ β β β’ risk_metrics β β
β β Design System β β β β’ technical_analysisβ β
β β Terminal Noir β β β β’ sec_parser β β
β β #0A0A0F bg β β β β’ news_aggregator β β
β β #00D4AA accent β β β β’ gemini_service β β
β β #FF4757 red β β β β’ market_data β β
β ββββββββββββββββββββ β ββββββββββββ¬ββββββββββββ β
β β β β
β β ββββββββββββΌββββββββββββ β
β β β Data Sources β β
β β β β’ yfinance β β
β β β β’ yahooquery β β
β β β β’ SEC EDGAR API β β
β β β β’ Google Gemini β β
β β β β’ Finviz / RSS β β
β β ββββββββββββββββββββββββ β
ββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββ
```
---
## Tech Stack
| Layer | Technology |
|-------|-----------|
| **Frontend** | Next.js 14 (App Router), TypeScript, Tailwind CSS |
| **Charts** | TradingView Lightweight Charts (candlestick, volume) |
| **Backend** | Python 3.12+, FastAPI, Pydantic v2, Uvicorn |
| **AI / LLM** | Google Gemini 2.0 Flash (`google-generativeai`) |
| **Financial Data** | yfinance (primary), yahooquery (fallback) |
| **Technical Indicators** | `ta` library (RSI, MACD, Bollinger, Ichimoku, ADX) |
| **Valuation Engine** | NumPy (Monte Carlo), SciPy (Brent root-finding for Reverse DCF) |
| **SEC Data** | `sec-edgar-downloader`, EDGAR REST API, BeautifulSoup4 + lxml |
| **Database** | SQLite (local) / PostgreSQL (production) via asyncpg |
| **News** | Finviz scraping + Google News RSS via feedparser |
| **Design System** | Terminal Noir β custom dark theme (#0A0A0F, #00D4AA, #FF4757) |
---
## Project Structure
```
atlas-terminal/
β
βββ apps/web/ # Next.js 14 Frontend
β βββ src/app/
β β βββ page.tsx # Overview (home)
β β βββ research/page.tsx # AI Research
β β βββ valuation/page.tsx # DCF + Sensitivity + Monte Carlo + Tornado + Reverse DCF
β β βββ technical/page.tsx # Technical Analysis (TradingView charts)
β β βββ markets/page.tsx # Financial Statements table
β β βββ earnings/page.tsx # Earnings history & calendar
β β βββ news/page.tsx # News feed (split-view)
β β βββ portfolio/page.tsx # Portfolio tracker
β β βββ filings/page.tsx # SEC EDGAR filing viewer
β β βββ settings/page.tsx # API keys configuration
β β βββ components/
β β β βββ sidebar.tsx # Navigation sidebar
β β β βββ ticker-bar.tsx # Live market indices bar
β β β βββ chat-panel.tsx # AI Copilot chat interface
β β βββ lib/
β β βββ use-ticker.ts # Ticker state hook (localStorage + CustomEvent)
β β βββ api.ts # API helper functions
β βββ next.config.mjs # API proxy: /api/* β localhost:8000
β βββ tailwind.config.ts # Terminal Noir color system
β βββ package.json
β
βββ server/ # FastAPI Backend
β βββ main.py # App entry + CORS + router mounting
β βββ routers/ # 13 API route handlers
β β βββ market_data.py # Stock quotes, indices, overview
β β βββ financials.py # Income statement, balance sheet, cash flow
β β βββ valuation.py # DCF, sensitivity, Monte Carlo, tornado, reverse DCF
β β βββ technical.py # RSI, MACD, Bollinger, moving averages, Fibonacci
β β βββ earnings.py # EPS history, calendar, quarterly data
β β βββ insider.py # Insider transactions, institutional holders
β β βββ edgar.py # SEC 10-K section extraction
β β βββ analysis.py # Gemini AI analysis endpoints
β β βββ news.py # News aggregation
β β βββ portfolio.py # Position CRUD + risk metrics
β β βββ estimates.py # Analyst estimates
β β βββ crypto.py # Cryptocurrency prices
β β βββ fx.py # FX rates and history
β βββ services/ # 15 business logic modules
β β βββ dcf_engine.py # Excel-style DCF, 2-stage DCF, reverse DCF (scipy brentq)
β β βββ monte_carlo.py # Monte Carlo simulation (5000 runs, numpy)
β β βββ sensitivity.py # WACC Γ TG matrix, tornado data
β β βββ risk_metrics.py # VaR, Sharpe, Sortino, MDD, Beta, Correlation
β β βββ technical_analysis.py # All indicators via `ta` library
β β βββ sec_parser.py # SEC EDGAR download, HTML parse, section cache
β β βββ news_aggregator.py # Finviz + Google News RSS
β β βββ gemini_service.py # Gemini API wrapper
β β βββ gemini_analysis.py # Structured AI analysis prompts
β β βββ market_data.py # Market overview, sector data
β β βββ financial_metrics.py # DuPont, Altman Z, ratio calculations
β β βββ ... # crypto, fx, screenshot OCR, text chunker
β βββ models/ # Pydantic schemas
β βββ db/ # SQLite + PostgreSQL repositories
β βββ ai/ # LLM router, context builder
β βββ utils/ # safe_float, ticker utilities
β
βββ tests/ # pytest test suite
βββ supabase/migrations/ # Database schema
βββ requirements.txt # Python dependencies
```
---
## API Endpoints
| Prefix | Methods | Description |
|--------|---------|-------------|
| `/api/market` | GET | Stock quotes, company info, market overview, sector data |
| `/api/financials` | GET | Income statement, balance sheet, cash flow, highlights, ratios |
| `/api/valuation` | GET, POST | DCF defaults, sensitivity matrix, Monte Carlo, tornado, reverse DCF |
| `/api/technical` | GET | RSI, MACD, Bollinger, moving averages, Fibonacci, ATR, ADX |
| `/api/earnings` | GET | EPS history, earnings calendar, quarterly data |
| `/api/insider` | GET | Insider transactions, institutional holders |
| `/api/edgar` | GET | SEC 10-K section extraction, Item 7 MD&A, filing comparison |
| `/api/analysis` | POST | Gemini AI analysis (MD&A, risk factors, financial health) |
| `/api/estimates` | GET | Analyst consensus estimates |
| `/api/news` | GET | Financial news aggregation (Finviz + Google News) |
| `/api/portfolio` | GET, POST, DELETE | Position management, risk metrics |
| `/api/crypto` | GET | Cryptocurrency prices (BTC, ETH, SOL, etc.) |
| `/api/fx` | GET | FX rates and historical data |
| `/health` | GET | Liveness probe with DB status |
Full interactive API documentation available at `http://localhost:8000/docs` (Swagger UI).
---
## Quick Start
### Prerequisites
- Python 3.12+
- Node.js 18+
- [Google Gemini API Key](https://aistudio.google.com/apikey) (for AI features)
- Email address for SEC EDGAR fair-access compliance
### Installation & Launch
```bash
# Clone the repository
git clone https://github.com/shawnkim1997/All-in-one-Financial-Analysis.git
cd "All-in-one-Financial-Analysis/atlas-terminal"
# ββ Backend ββ
pip install -r requirements.txt
PYTHONPATH="." uvicorn server.main:app --port 8000
# ββ Frontend (new terminal) ββ
cd apps/web
npm install
npm run dev
```
Open **http://localhost:3000** in your browser.
Configure your **Gemini API Key** and **SEC EDGAR email** in the Settings page, then search for any ticker (e.g., MSFT, AAPL, GOOGL) to explore.
---
## Design System β Terminal Noir
ATLAS Terminal uses a custom dark theme inspired by professional trading terminals:
| Token | Value | Usage |
|-------|-------|-------|
| `bg-primary` | `#0A0A0F` | Main background |
| `bg-card` | `#12121A` | Card surfaces |
| `bg-elevated` | `#1A1A2E` | Hover states, elevated panels |
| `border` | `#2A2A3E` | Borders and dividers |
| `accent-green` | `#00D4AA` | Positive values, CTAs, active states |
| `accent-red` | `#FF4757` | Negative values, warnings |
| `accent-blue` | `#4A9EFF` | Informational badges, links |
| `accent-yellow` | `#FFD93D` | Caution, highlights |
| `text-primary` | `#E8E8ED` | Primary text |
| `text-secondary` | `#A0A0B0` | Secondary text |
| `text-muted` | `#6B6B80` | Muted labels |
---
## Evolution: Streamlit β Next.js + FastAPI
This project began as a **Streamlit prototype** (`app.py`, 3,909 lines) and has been fully migrated to a modern full-stack architecture:
| Aspect | Streamlit (v1-v3) | Next.js + FastAPI (v4) |
|--------|-------------------|----------------------|
| Frontend | Streamlit widgets | Next.js 14 App Router + Tailwind |
| Backend | Embedded in Streamlit | Dedicated FastAPI with 13 routers |
| Charts | Plotly (Sankey, Radar) | TradingView Lightweight Charts |
| State | `st.session_state` | React hooks + localStorage |
| Routing | Tab-based (7 tabs) | File-based (10 pages) |
| API | Monolithic | RESTful with OpenAPI docs |
| Caching | `@st.cache_data` | SQLite/PostgreSQL persistence |
| Deployment | Single process | Frontend + Backend independently scalable |
The original Streamlit version remains functional at the project root (`app.py`) for reference.
---
## Technical Highlights
### Hybrid AI Architecture
Gemini handles **text interpretation only** (MD&A analysis, risk factor extraction, industry outlook). All financial figures come from yfinance/yahooquery β zero hallucination risk on numbers.
### Multi-Source Data Resilience
Primary source (yfinance) with automatic yahooquery fallback. Pipe-separated multi-key column lookups handle naming differences between providers (`"TotalRevenue|Total Revenue|Revenue"`).
### Quantitative Valuation Suite
Five interconnected valuation models β DCF serves as the base, Sensitivity shows assumption impact, Monte Carlo quantifies uncertainty, Tornado ranks variable importance, and Reverse DCF reveals market-implied expectations.
### SEC EDGAR Integration
Full pipeline: `sec-edgar-downloader` β HTML parsing with BeautifulSoup β section extraction (Items 1A, 3, 7, 8, 9A) β local caching β AI summarization via Gemini.
---
## Requirements
See [`atlas-terminal/requirements.txt`](atlas-terminal/requirements.txt) for the full Python dependency list. Key packages:
- `fastapi`, `uvicorn` β Web framework
- `yfinance`, `yahooquery` β Financial data
- `google-generativeai` β Gemini AI
- `sec-edgar-downloader`, `beautifulsoup4`, `lxml` β SEC filing parsing
- `ta` β Technical analysis indicators
- `numpy`, `scipy` β Monte Carlo simulation, optimization
- `pandas` β Data manipulation
Frontend: `next`, `react`, `tailwindcss`, `lightweight-charts`
---
## Update History (Changelog)
| Date | Update |
|------|--------|
| **2026-03-21** | **Full-stack migration (v4.0) β Next.js 14 + FastAPI:** Complete rewrite from Streamlit to Next.js 14 App Router + FastAPI backend. 10 dedicated pages (Overview, Research, Valuation, Technical, Markets, Earnings, News, Portfolio, Filings, Settings). 13 REST API routers with Swagger docs. 5 valuation models (DCF, Sensitivity Matrix, Monte Carlo 5000-sim, Tornado, Reverse DCF with scipy brentq). TradingView Lightweight Charts for candlestick/volume. Technical Analysis page with RSI, MACD, Bollinger, Fibonacci, Moving Averages, ADX. Earnings beat/miss visualization. News split-view with iframe article embedding. SEC EDGAR inline filing viewer with 5 section tabs + AI Summary. Financial Statements table with YoY growth badges and margin rows. Terminal Noir dark theme design system. AI Copilot chat panel with Gemini. |
| **2026-03-19** | **Modular refactoring (v3.0) + SEC filing viewer fix:** (1) **Architecture:** 3,909-line `app.py` refactored into 28 focused modules across `config/`, `utils/`, `data/`, `ai/`, `views/`. Each file under 300 lines. Strict unidirectional dependency graph (no circular imports). All `@st.cache_data` TTLs and `st.session_state` keys preserved identically. (2) **SEC Filing Viewer fixed:** Rebuilt EDGAR fetch chain using `submissions/CIK{cik}.json` β `filings.recent.primaryDocument[]` (replaces deprecated `directory.item` lookup). Added filing type `st.selectbox` (10-K, 10-Q, 8-K, 20-F, 6-K) connected to backend dynamically. Native HTML rendered via `streamlit.components.v1.html()` with injected CSS reset. Errors surfaced explicitly with `st.error()`. (3) **DART links** restored for Korean-listed companies. |
| **2026-02-18** | **Market Heatmap & FX charts:** Sector heatmap with 5d/1mo data and per-ticker fallback (weekend/holiday robust). FX Momentum normalized 1Y line chart (GBP/USD, EUR/USD, USD/JPY, KRW). 10-K language toggle (νκΈ/μλ¬Έ) via Gemini translation. plotly/yfinance added to requirements. |
| **2026-02-17** | **DART, prefs, run script:** DART fetch timeout 90s; DART report titles in English (cached). SEC & DART per-category iframe viewer. Last selected company persisted in `.app_prefs.json` (survives page refresh). Single run script `run.sh` at port 8501. |
| **2025-02-15** | **Multi-currency portfolio & FX:** Per-position currency (USD/GBP/EUR/KRW/JPY/CNY), fractional quantity, FX-adjusted returns. Gemini Vision AI screenshot import (extracts ticker, price, currency, quantity). App-wide `get_currency_for_ticker`, `get_fx_rate`, `format_price_with_usd`. |
| **2025-02-14** | **Global company search:** yahooquery `search()` replaces static dropdown. Search by name in any language; filters INDEX/MUTUALFUND; auto-infers .KS/.KQ/.T/.L suffix. |
| **2025-02-13** | **Design Rationale & 10Y DCF:** Design rationale section (undergrad automation mindset, 10Y 2-stage DCF, Damodaran integration). Wall Street Assumptions panel (analyst consensus + Damodaran baselines). Smart DCF defaults from Beta/CAPM. |
| **2025-02-13** | **Robust data & comps redesign:** Multi-step shares/debt/cash fallback (fast_info β info β balance). Top-down sector analysis with `SECTORS` dict and AI Industry Outlook (Gemini). |
| **2025-02-12** | **Hybrid architecture:** Item 7 only to Gemini; yfinance for all numbers. HTML cleansing pipeline (BeautifulSoup + regex). |
| **2025-02-12** | **DuPont, Altman Z, Piotroski, sector KPIs, TTM fallback:** Full quantitative financial health suite. Sector-specific metrics (Tech: Rule of 40; Retail: Inventory Turnover; Financials: ROE/ROA). |
| **2025-02-12** | **Preference persistence:** "Remember API key & email" checkbox; `.app_prefs.json` (gitignored). |
| **2025-01-XX** | **Initial release:** SEC EDGAR 10-K download, Item 7/8 extraction, Gemini analysis, Streamlit UI. |
---
## License & Disclaimer
This project is built for learning, research, and portfolio demonstration purposes. Nothing in this application constitutes investment advice. Comply with [SEC EDGAR policy](https://www.sec.gov/os/webmaster-faq#code-support) when accessing SEC data, and with Google's terms of service for the Gemini API.
---
Built with β and late nights β @shawnkim1997