StockHealth: shipping a 7-layer portfolio brain solo

I wanted a stock tracking tool that gave me signal, not noise. Every app I tried optimised for activity — alerts, charts, numbers refreshing constantly — without telling me the one thing I actually needed to know: should I be thinking about this holding right now, and why?

So I built StockHealth. It runs on a free-tier stack and costs ₹0 a month. It sends me three Telegram briefs a day. And it has made me a meaningfully better investor — not because it's smart, but because it forces me to think in the right structure.

Here's what I learned building it.

The PM problem first

Before I wrote a line of code, I wrote a product brief. Not because I was trying to be rigorous — because I've seen what happens when you build without one.

The brief had three questions:

Who is this for? (Me, specifically. Not "retail investors".)
What's the job to be done? (Give me one clear read on each holding, sorted by what matters most today.)
What does success look like? (I open the brief. I make a decision or I don't. I move on.)

That last one was the hardest. Most dashboards define success as "user opened the product." I needed to define it as "user made a confident decision in under 2 minutes." Different problem entirely.

Why 7 layers

The 7 context layers aren't arbitrary. They map to the actual questions I ask before deciding whether to act on a holding:

Fundamentals — Is this a good business? (P/E, P/B, ROE, debt)
Sector benchmarks — Is it a good business relative to its peers?
Technicals — What's the short-term momentum? (RSI, MACD, Bollinger Bands)
News — Is there something material I should know about?
Earnings — What happened last quarter? What's the street expecting?
Portfolio impact — How does this holding affect my overall exposure?
Stateful memory — What did I think about this stock last time? Has anything changed?

Layer 7 is the one that makes StockHealth different from a Bloomberg terminal. Most tools have no memory. They treat every session as fresh. I wanted the bot to remember: "Last Tuesday you were watching HDFC Bank for a breakout. It hasn't broken out. Here's why."

That conviction score (1–10) per holding, updated each session, is the feature that actually changed my behaviour.

The build

Stack: Python, SQLite, Gemini 1.5 Flash (contextual reasoning), Groq/Llama (fast synthesis), yfinance + NSE APIs, pandas-ta (technicals), Python Telegram Bot.

Architecture: Three scheduled jobs (pre-market, mid-session, post-close) → data collection → context assembly → LLM synthesis → Telegram delivery.

The hardest part wasn't the code. It was prompt engineering the synthesis layer to produce brief output. LLMs, left unconstrained, will produce 500 words where I need 80. Getting the model to synthesise 7 layers of context into "here's your one actionable read on this holding, in three sentences" took longer than all the data plumbing combined.

The PM lesson: Constraints are features. The 80-word limit per holding isn't just an interface choice — it's the product thesis. If I can't say it in 80 words, I don't understand it well enough to act.

What I'd do differently

Build the data model first. I changed the SQLite schema three times because I hadn't thought through the stateful memory layer properly. If I'd spent an hour on the data model, I'd have saved a day of refactoring.
Ship the bad version faster. The first brief I ever sent myself was ugly. Text walls, no structure, wrong sorting. But sending it forced me to confront what was actually wrong — in a way that staring at code never would.
Talk to one other user earlier. I built this for me. But a friend started using it after I showed him, and the first thing he asked for was something I hadn't considered: a weekly summary brief for people who don't check every day. Different job to be done, same product.

The line that guided everything

The interface is the product. If the brief is confusing, the analysis doesn't matter.

I kept this written above my desk for the three months I was building StockHealth. Every time I was tempted to add another data point or a new chart, I came back to it.

StockHealth is live on my personal Telegram. The code is on GitHub. If you're building something similar and want to compare notes, email me.