supply-chain

Generate an interactive supply chain dashboard for the company named in the user's request. If no ticker or company is provided, ask for one before proceeding. **Before starting, read `../data-access.md` for data access methods and `../design-system.md` for formatting conventions.** Follow the data access detection logic and design system throughout this skill. This skill maps the upstream (supplier) and downstream (customer) relationships for a target company, quantifying financial interdependencies in both directions. The output enables an analyst to understand: Who are the critical suppliers and customers? Where is concentration risk on both sides? Which suppliers depend heavily on this company for revenue? Which customers depend on this company's products as critical inputs? How does a shock propagate both upstream (demand shock to suppliers) and downstream (supply disruption to customers)? ## Output Format The final deliverable is a **single self-contained HTML file** with: - Embedded CSS and JavaScript (no external dependencies) - **Tier-grouped Canvas network visualization** — columns: Tier 3 → Tier 2 → Tier 1 → Target → Customers, with connection lines. Clickable nodes open detail overlays. - **Inventory Health Overview table** — for all suppliers: RM%, WIP%, FG% of total inventory shown as stacked colored bars, plus latest total inventory value - **Supplier cards grouped by tier** — Tier 1 (Critical/Sole-source), Tier 2 (Major Component), Tier 3 (Specialty) with click-to-expand detail overlays - **Detail overlays** for each supplier containing: - 10-quarter financial table (Revenue, Gross Profit, Net Income, Gross Margin %) - 10-quarter inventory breakdown table (Raw Materials, WIP, Finished Goods, Total, RM%, WIP%, FG%) - Canvas chart: stacked bar chart of inventory composition with Gross Margin % line overlay - Business description and relationship to target company - **Customer cards grouped by category** — Channel Partners, Enterprise/B2B, End-Market Exposure — with click-to-expand detail overlays matching supplier depth - **Detail overlays** for each customer containing: - 10-quarter financial table (Revenue, Gross Profit, Net Income, Gross Margin %) - 10-quarter inventory breakdown table (Raw Materials, WIP, Finished Goods, Total, RM%, WIP%, FG%) - Canvas chart: stacked bar chart of inventory composition with Gross Margin % line overlay - Business description and relationship to target company - **Upstream Shock Analysis** section — narrative analysis of how a demand/supply shock to the target company ripples upstream through the supplier chain, with an impact matrix table (Revenue Impact, Margin Impact, Overall Risk per supplier) - **Downstream Shock Analysis** section — narrative analysis of how a supply disruption at the target company ripples downstream through the customer chain, with an impact matrix table (Input Criticality, Switching Cost, Revenue at Risk, Overall Disruption Risk per customer) - All financial figures hyperlinked to Daloopa source citations - A "Download as PDF" button (uses `window.print()`) **DOM Safety**: All JavaScript MUST use `createElement()` + `textContent` + `appendChild()` for DOM construction. NEVER use `innerHTML`, `outerHTML`, or any HTML-string injection methods. Use helper functions like `ce(tag)`, `ca(el, attrs)`, `cA(parent, children)` to keep code compact. Save to `reports/{TICKER}_supply-chain.html` and open it with `open`. --- ## RESEARCH WORKFLOW This is a multi-phase research process. Each phase builds on the previous one. Maximize parallelism across independent API calls. ### Phase 1: Target Company Identification 1. Use `discover_companies` with the ticker symbol to get the `company_id`, `latest_calendar_quarter`, and `latest_fiscal_quarter`. Note the firm name for report attribution (default: "Daloopa") — see `../data-access.md` Section 4.5. 2. Pull key financials for the target company: - Use `discover_company_series` with keywords: ["revenue", "cost of goods", "gross profit", "operating income", "net income", "total cost"] - Calculate 4 quarters backward from `latest_calendar_quarter`. Use `get_company_fundamentals` for those periods to get TTM figures. 3. Note the target company's total COGS / cost of revenue (TTM) — this is the denominator for supplier % calculations. ### Phase 2: Supplier Identification Run these concurrently to build a comprehensive supplier list: **2a. Daloopa Document Search:** - Search keywords: ["supplier", "vendor", "purchase", "procurement"] across last 2-4 quarters - Search keywords: ["supply agreement", "supply chain", "manufacturing"] across last 2-4 quarters - Search keywords: ["sole source", "single source", "key supplier"] across last 2-4 quarters - Search keywords: ["concentration", "significant supplier"] across last 2-4 quarters - Search the company's 10-K specifically for supplier disclosures **2b. Web Research:** - `"[TICKER] [company name] key suppliers list 2025 2026"` — supplier identification - `"[TICKER] supply chain analysis suppliers"` — analyst/industry reports - `"[TICKER] 10-K supplier disclosure"` — SEC filing analysis - `"[company name] supply chain map"` — industry supply chain maps - `"[company name] supplier concentration risk"` — risk analysis - `"[company name] who manufactures for [company]"` — manufacturing partners - `"[company name] component suppliers"` — component-level supply chain **2c. Industry-Specific Supplier Research:** For each industry, search for the known critical supply chain relationships: - **Tech/Hardware**: semiconductor foundries (TSMC, Samsung), display (Samsung, LG, BOE), memory (Samsung, SK Hynix, Micron), sensors/cameras (Sony), glass (Corning), connectors (Amphenol), batteries (CATL, LG Energy), PCB/assembly (Foxconn/Hon Hai, Pegatron, Luxshare) - **Automotive**: battery (CATL, Panasonic, LG Energy), semiconductors (Infineon, NXP, ON Semi, TI), steel (Nippon, POSCO), tires (Michelin, Bridgestone), glass (AGC, Saint-Gobain) - **Pharma**: CDMOs (Lonza, Samsung Biologics, Catalent), API suppliers, packaging, distribution - **Retail**: brand suppliers, logistics (FedEx, UPS), packaging - **Energy**: equipment (Baker Hughes, Schlumberger), pipe (Tenaris), chemicals ### Phase 3: Supplier Financial Analysis For each identified supplier (aim for 8-15 key suppliers): 1. **Discover the supplier** using `discover_companies` with their ticker 2. **Pull key financials** from Daloopa: - `discover_company_series` with keywords: ["revenue", "net income", "gross margin", "operating margin"] - `get_company_fundamentals` for the same 4 calendar quarters as the target company 3. **Determine revenue concentration**: - Search Daloopa documents for the supplier: keywords ["[target company name]", "customer", "concentration"] - Web search: `"[supplier name] [target company] revenue percentage customer"` - Web search: `"[supplier name] 10-K customer concentration"` - Many suppliers disclose their top customers in 10-K filings — look for "customers that accounted for 10% or more of revenue" 4. **Determine COGS attribution** (what % of target's costs is this supplier): - This is often estimated. Use logic like: - If Apple's COGS is ~$200B TTM and TSMC's revenue from Apple is ~$70B, then TSMC = ~35% of COGS - Cite the source of each estimate (analyst report, 10-K disclosure, industry research) - Flag when this is an estimate vs. a disclosed figure 5. **Business & product description**: What does this supplier provide? Be specific (e.g., "5nm/3nm chip fabrication for A-series and M-series SoCs" not just "semiconductors") ### Phase 3b: Inventory & 10-Quarter Financial Data For the target company AND each identified supplier (8-15 companies), pull **10 quarters** of data: 1. **Discover inventory series** using `discover_company_series` with keywords: ["raw material", "work in process", "finished good", "inventory", "inventories"] - Look for separate RM, WIP, FG series, plus a total inventory series - Some companies report "carrying amount" breakdowns — use those for RM/WIP/FG splits 2. **Discover financial series** using `discover_company_series` with keywords: ["revenue", "gross profit", "net income", "gross margin"] 3. **Pull 10 quarters** using `get_company_fundamentals`. Calculate 10 quarters backward from `latest_calendar_quarter`. - Example: if latest is Q4'25, pull ["2023Q3", "2023Q4", "2024Q1", "2024Q2", "2024Q3", "2024Q4", "2025Q1", "2025Q2", "2025Q3", "2025Q4"] 4. **Compute inventory composition**: For each quarter, calculate RM%, WIP%, FG% of total inventory - High WIP% can signal production bottlenecks - Rising FG% can signal demand weakness - Rising RM% can signal supply hoarding or procurement buildup 5. **Handle missing data gracefully**: Some suppliers may not report full inventory breakdowns — show what's available and note gaps 6. **Multi-currency handling**: Note the reporting currency for each company (USD, NTD, KRW, EUR, etc.) and display with appropriate units (e.g., "NTD B" for TSMC, "KRW T" for Samsung) Run inventory and financial series pulls in parallel across all companies. ### Phase 4: Customer / Downstream Identification The downstream side requires the same research rigor as the upstream side. Run these concurrently to build a comprehensive customer list: **4a. Daloopa Document Search (target company filings):** - Search keywords: ["customer", "contract", "agreement", "channel"] across last 2-4 quarters - Search keywords: ["customer concentration", "significant customer", "major customer"] across last 2-4 quarters — many companies disclose customers >10% of revenue - Search keywords: ["distribution", "retail partner", "reseller", "licensee"] across last 2-4 quarters - Search keywords: ["accounts receivable", "contract asset", "deferred revenue"] — concentration in A/R often reveals customer dependency even when not explicitly named - Search the company's 10-K specifically for customer disclosures and segment end-market breakdowns **4b. Web Research:** - `"[TICKER] [company name] major customers list"` — direct customer identification - `"[TICKER] customer concentration revenue breakdown"` — analyst/industry reports - `"[TICKER] 10-K customer disclosure"` — SEC filing analysis - `"[company name] who buys from [company name]"` — downstream identification - `"[company name] channel partners distributors"` — channel analysis - `"[company name] end market exposure"` — end-market breakdown **4c. Industry-Specific Customer Research:** For each industry, search for the known critical downstream relationships: - **Semiconductors**: Which OEMs depend on these chips? (e.g., NVDA → hyperscalers MSFT/AMZN/GOOG, QCOM → smartphone OEMs AAPL/Samsung, AVGO → networking OEMs Cisco/Arista) - **Components/Materials**: Which assemblers or product companies use these inputs? (e.g., Corning → AAPL/Samsung for glass, TSMC → fabless semis NVDA/AMD/AAPL) - **Software/Platform**: Who builds on this platform? (e.g., MSFT Azure → ISVs, AAPL App Store → developers, Salesforce → SI partners) - **Consumer products**: Channel partners (carriers, retailers, e-commerce) and enterprise customers - **Industrial/B2B**: End-market verticals (auto, aerospace, medical, telecom) - **Pharma/Biotech**: Distributors (McKesson, AmerisourceBergen), PBMs, hospital systems **4d. Customer Financial Analysis:** For each identified customer (aim for 6-10 key customers): 1. **Discover the customer** using `discover_companies` with their ticker 2. **Pull key financials** from Daloopa: - `discover_company_series` with keywords: ["revenue", "net income", "gross margin", "cost of goods", "operating income"] - `get_company_fundamentals` for the same 4 calendar quarters as the target company 3. **Determine revenue attribution** (what % of target's revenue comes from this customer): - Search Daloopa documents for the target company: keywords ["[customer name]", "customer", "concentration", "accounts receivable"] - Web search: `"[target company] [customer name] revenue percentage"` - Web search: `"[target company] 10-K customer concentration"` - Many companies disclose customers that account for >10% of revenue in their 10-K 4. **Determine input criticality** (what % of customer's COGS comes from target): - This is the inverse of the supplier analysis: if the target sells $X to a customer with $Y in COGS, then input share = X/Y - Search for: `"[customer name] [target company] supplier dependence"` or `"[customer name] key inputs components"` - Flag whether the target's product is a critical, hard-to-substitute input vs. a commodity with alternatives 5. **Assess switching costs**: Can the customer easily replace the target company's product? - **High switching cost**: Custom/proprietary integration, long qualification cycles, regulatory requirements (e.g., TSMC's process node — customers can't easily switch foundries mid-design) - **Medium switching cost**: Some integration required but alternatives exist with 6-12 month transition - **Low switching cost**: Commodity input, multiple qualified alternatives, short switching timeline 6. **Business & product description**: What does the target supply to this customer? Be specific (e.g., "A17 Pro and M4 SoCs fabricated on TSMC's 3nm process" not just "chips") ### Phase 4e: Customer Inventory & 10-Quarter Financial Data Mirror Phase 3b for the customer side. For each identified customer (6-10 companies), pull **10 quarters** of data: 1. **Discover inventory series** using `discover_company_series` with keywords: ["raw material", "work in process", "finished good", "inventory", "inventories"] - Look for separate RM, WIP, FG series, plus a total inventory series 2. **Discover financial series** using `discover_company_series` with keywords: ["revenue", "gross profit", "net income", "gross margin"] 3. **Pull 10 quarters** using `get_company_fundamentals` with the same 10 calendar quarters as the target company and suppliers (calculated from `latest_calendar_quarter`) 4. **Compute inventory composition**: RM%, WIP%, FG% of total inventory - For customers, inventory signals have different meaning: - Rising RM% at a customer → they're stocking up on target company's inputs (bullish for target's near-term revenue, but may mean future destocking) - Falling RM% → customer is drawing down inventory, may signal reduced orders ahead - Rising FG% at a customer → demand for the customer's end product is softening, which will flow back upstream to the target 5. **Handle missing data gracefully**: Some customers may not report inventory breakdowns — show what's available 6. **Multi-currency handling**: Same as suppliers — note reporting currency Run customer inventory and financial series pulls in parallel, and in parallel with supplier pulls where possible. ### Phase 5: Tier 2 Supplier Research For the top 3-5 most important Tier 1 suppliers, repeat a lighter version of Phase 2-3: 1. Identify their key suppliers (Tier 2 to the original target) 2. Pull basic financials 3. Determine what they supply and rough revenue/cost relationships 4. This enables the "drill deeper" functionality in the dashboard ### Phase 6: Data Assembly & Synthesis Before writing HTML, organize all data into this structure: ``` TARGET COMPANY: - Name, ticker, description - TTM Revenue, COGS, Gross Profit, Net Income, Gross Margin, Op Margin - Market cap, stock price (from web) TIER 1 SUPPLIERS (sorted by estimated % of target COGS, descending): For each: - Name, ticker, description - What they supply (specific products/components) - Estimated % of target company COGS (with source/logic) - % of supplier revenue from target company (with source) - TTM Revenue, Net Income, Gross Margin - Market cap - Relationship summary (sole source? multi-source? critical?) - Their key suppliers (Tier 2) if researched - 10-quarter financials: Revenue, Gross Profit, Net Income, GM% (with Daloopa citation IDs) - 10-quarter inventory: RM, WIP, FG, Total, RM%, WIP%, FG% (with Daloopa citation IDs) - Reporting currency and unit (e.g., USD $M, NTD B, KRW T) TIER 1 CUSTOMERS (sorted by estimated % of target revenue, descending): For each: - Name, ticker, description - What target company supplies to them (specific products/services) - Estimated % of target revenue from this customer (with source/logic) - Estimated % of customer COGS from target (input criticality, with source) - Switching cost assessment (High/Medium/Low with reasoning) - TTM Revenue, COGS, Net Income, Gross Margin - Market cap - Relationship summary (exclusive? multi-source? long-term contract? spot?) - 10-quarter financials: Revenue, Gross Profit, Net Income, GM% (with Daloopa citation IDs) - 10-quarter inventory: RM, WIP, FG, Total, RM%, WIP%, FG% (with Daloopa citation IDs) - Reporting currency and unit (e.g., USD $M, EUR M, JPY B) TIER 2 CUSTOMERS (for top 3-5 Tier 1 customers — who do THEY sell to?): For each Tier 1 customer, their key customers with basic data This traces the value chain forward: Target → Customer → End Market TIER 2 SUPPLIERS (for top 3-5 Tier 1 suppliers): For each Tier 1 supplier, their key suppliers with basic data ``` ### Phase 6b: Upstream Shock Analysis (Demand Shock → Suppliers) Prepare a narrative analysis of how a demand shock at the target company would ripple upstream through the supplier chain: 1. **Classify each supplier by dependency level**: - **High dependency**: Target company is >20% of supplier's revenue → severe impact from demand shock - **Moderate dependency**: Target is 10-20% of revenue → meaningful but manageable impact - **Low dependency**: Target is <10% of revenue → diversified, minimal direct impact 2. **Assess shock propagation for each supplier**: - **Revenue Impact** (High/Medium/Low): Based on % of revenue from target - **Margin Impact** (High/Medium/Low): Based on operating leverage, fixed costs, ability to find replacement demand - **Inventory Risk**: Suppliers with high FG% are more exposed to demand shocks; those with high RM% face supply-side risk - **Substitutability**: Can the target switch to alternatives? Can the supplier find other customers?