EquityWise
Tracking, analysis and screening for NSE equities. It shows what the market and
each stock are doing — trend, breakouts, momentum, volume, delivery, ownership,
events — from data, and lets each user screen and watch on conditions they choose.
It describes; it never picks stocks, issues buy/sell signals, simulates trades, or
places, manages or represents an order. See CLAUDE.md for the hard
rules that govern everything added on top, and OVERVIEW.md for a
cold-read tour of the whole system.
Layout
apps/
web/ Next.js App Router + Tailwind — pages and the JSON API
worker/ croner scheduler — every job that ingests or computes market data
packages/
shared/ paise + IST/market-time helpers — everything depends on this
core/ pure calculations: indicators, screener metrics, IPOs, portfolio,
alerts, flows, exchange calendar, announcement interpretation
market-data/ the provider-neutral boundary (MarketDataProvider, routed provider)
db/ Drizzle schema, client, migrations, repositories
fyers/ Fyers API v3 client
providers-fyers/ the Fyers adapter — the only place Fyers types and ours co-exist
dhan/ Dhan API v2 client
providers-dhan/ the Dhan adapter
config/ versioned YAML: indices, market calendar, IPO sources, screener presets
docs/ architecture, operations, planning, design system — see docs/README.md
scripts/ one-off operations and verification scripts
test/ integration-test helpers and the Playwright release smoke
tracker/ standalone Markdown work tracker; not part of the workspace
docs/planning/pending-features.md carries the
code-verified status ledger: what is finished, what is built but unwired, and what
is still a plan.
What is built
Every signed-in user gets:
| Page | What it shows |
|---|
/today | Market Brief — a technical summary of the latest completed session |
/watchlists | per-user lists with configurable columns, saved views and live quotes |
/screener | the whole NSE EQ/BE/BZ universe filtered on ~95 nightly metrics; saved screens |
/stocks/[symbol] | one stock: price chart, ratio board, "What stands out" facts, dividends and its screener metrics |
/markets/breadth | advance/decline and participation across the universe |
/flows | institutional flow — FII/DII cash, bulk/block deals, delivery, participant OI |
/announcements | NSE/BSE corporate filings, categorised |
/calendar | market holidays, results, corporate actions and watchlist events |
/ipos | mainboard and SME IPOs from NSE, with an always-labelled unofficial GMP |
/portfolio | the user's own hand-typed or imported holdings, valued at the last price |
/alerts | price or RSI level crossings on a completed session |
/admin (user administration, logs, IPO pipeline health) is restricted to the
admin role. There are no fundamentals (P/E, ROE, market cap) — that needs a new
data source.
Signals, setups and paper trading were removed on 2026-10-17
(plan and record). The app
states facts about the data; it never ranks stocks by its own conviction.
Setup
pnpm install
cp .env.example .env # then fill in the two database connection strings
pnpm build
pnpm --filter @equitywise/worker dev # schedules every job; never mints a credential
.env.example documents each variable. The short version: both DATABASE_URL
and DATABASE_URL_DIRECT point at the self-hosted Postgres (identical on the VPS
and over a local SSH tunnel, since there is no pooler). Migrations run against
DATABASE_URL_DIRECT — drizzle.config.ts refuses a pooled URL.
Run one job now, or a deep history pull:
pnpm --filter @equitywise/worker dev -- --once ingest-daily
pnpm --filter @equitywise/worker dev -- --backfill
Never point a local worker at production. It writes to the live database, and
a credential mint kills the live Fyers token (one session per account). The dev
script sets WORKER_MINT_CREDENTIALS=false for that reason; local web-only work
against the VPS database is covered in
docs/operations/deployment.md.
Deploying (single VPS)
Both processes run on one Ubuntu VPS behind Nginx. Node 24 (see .nvmrc), pnpm,
and PM2 keep the web app (next start -p 3000) and the worker alive; Nginx
terminates SSL and reverse-proxies :443 → :3000. Deploys are automatic — merge
to main and GitHub Actions ships it, then runs a post-deploy smoke
(scripts/post-deploy-smoke.sh). The complete as-built reference — server,
pipeline, self-hosted Postgres, credentials, backups, DNS/SSL, local dev, and
operations — is docs/operations/deployment.md;
this section is only the shape.
Build with pnpm build (topological tsc, then next build), then start each
process under PM2. .env is gitignored; on the VPS it lives outside the checkout,
root-owned and chmod 600, and next.config.ts dotenv-loads the repo-root file.
The web app needs DATABASE_URL, the AUTH_* values (AUTH_SESSION_SECRET is
required in production; sign-up refuses to write without it), RESEND_API_KEY /
AUTH_EMAIL_FROM for account email, GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
when Google sign-in is on, and MARKET_DATA_PROVIDER plus the provider app IDs for
live quotes. The login factors (FYERS_ID, FYERS_TOTP_SECRET, FYERS_PIN,
DHAN_PIN, DHAN_TOTP_SECRET) belong to the worker only. next build succeeds
without any of them — a missing value is a runtime failure, not a build error.
Market-data credentials
Market-data tokens expire daily, and each new one starts from a 2FA login. Nobody
does that by hand here.
The worker holds the login factors, mints tokens and writes them to
provider_credentials. The web app reads that table and never mints anything.
| Job | When (IST) | What it does |
|---|
refresh-credential | 07:05 weekdays, and at startup | mints every held provider's token after Fyers' 07:00 expiry |
credential-rollover | 01:35 daily | renews Dhan's 24-hour token in the middle of the night |
probe-credentials | every 5 min, 09:00–15:59 Mon–Sat | one authenticated call per provider; a rejected token is re-minted (at most once per 10 min) |
That split is the security boundary, not an implementation detail. The TOTP seed
is the same 2FA secret that protects the brokerage login, including the
order-placing side this app deliberately has nothing to do with. It stays on a
host you control. What reaches the web app is a token that dies within the day and
can only read market data — so a compromise of the deploy costs a day of quote
access, not the account.
Setting only some of a provider's factors is reported at startup rather than
silently never refreshing. A refresh failure is logged loudly and does not fall
back to the stale token, because a request sent with an expired credential fails
upstream as an opaque authorisation error that hides the real cause.
The manual paths still exist: pnpm fyers:login writes FYERS_ACCESS_TOKEN into
.env, and an admin can run the Fyers OAuth handshake from the web app
(/api/fyers/connect → /callback). The daily refresh removes the need for either.
Scripts
| Command | What it does |
|---|
pnpm dev | every package in watch mode, plus next dev and the worker |
pnpm dev:web | the web app only |
pnpm build | topological tsc build, then next build |
pnpm test | Vitest across the workspace |
pnpm test:coverage | ditto, with a v8 coverage report |
pnpm test:integration | DB-backed suites against a throwaway TimescaleDB container |
pnpm test:db:up / test:db:down | start / drop that container |
pnpm test:e2e | Playwright release smoke (test/e2e) |
pnpm lint | Biome lint + format check |
pnpm lint:fix | Biome, writing fixes |
pnpm typecheck | tsc --noEmit per package |
pnpm db:generate | drizzle-kit: SQL migration from the schema |
pnpm db:migrate | drizzle-kit: apply migrations (direct endpoint) |
pnpm db:studio | drizzle-kit studio |
pnpm fyers:login | manual Fyers token mint into .env |
pnpm dhan:probe | read-only checks against the Dhan API |
pnpm verify:adjustment | check whether the provider back-adjusts split history |
pnpm data:coverage | report stored candle history and what recent ingestion runs did |
pnpm data:seed-disclosures | seed sample filings and flows into a dev database (never production) |
Database integration tests
Most of the suite is pure and needs nothing. The DB-backed suites — the ones that
assert schema-level guarantees a mock could never catch (one default watchlist per
user, no duplicate stock in a list, append-only alert history) — need a real
Postgres they may migrate from empty and throw away.
That database is local and disposable, run from docker-compose.test.yml:
Postgres 17 + TimescaleDB, the same stack the VPS runs, so the migrations'
CREATE EXTENSION and hypertables execute for real.
pnpm test:integration # up → migrate → full suite → down (ephemeral, tmpfs)
That is the whole workflow — it needs no configuration. Under the hood it starts
the container, sets TEST_DATABASE_URL, and Vitest's global setup migrates the
schema once before any suite.
For an iterative loop, keep the database up and run the watcher against it:
pnpm test:db:up # start the container (port 5433)
TEST_DATABASE_URL="postgresql://equitywise:equitywise@localhost:5433/nse_signals_test" pnpm test:watch
pnpm test:db:down # stop it and drop the volume
Safety and skip rules (see test/db.ts):
TEST_DATABASE_URL must be local and its name must end in _test, or
the suites refuse to run — so a test can never migrate or truncate a real
database.- Unset locally, the DB suites skip (a machine without Docker still runs
every pure test). Unset in CI, they fail — CI always provides the
database, so the DB-enforced invariants can never quietly stop being tested.
CI runs this exact suite against a TimescaleDB service container
(.github/workflows/ci.yml).
Troubleshooting
Cannot find module './289.js' (or any numbered chunk) from apps/web.
Stale .next output. It happens when pnpm build runs while a Next server is
already serving that directory: the rebuild rewrites chunk hashes underneath the
live process, whose in-memory webpack runtime still points at the old ones.
lsof -ti:3000 | xargs kill # stop the server first
pnpm clean # drop .next and every dist/
pnpm build
Avoid it by stopping next dev / next start before a workspace-wide build.
TypeScript
tsconfig.base.json holds the shared settings — strict,
noUncheckedIndexedAccess, exactOptionalPropertyTypes, ES2022 target,
NodeNext modules — and every package extends it.
apps/web is the one exception: Next.js bundles rather than emitting
Node-resolvable output, so it overrides module/moduleResolution to
ESNext/Bundler and adds the DOM libs. Every strictness flag is inherited
unchanged.
Workspace packages compile to dist/ and are consumed through their exports
map, so pnpm build must run before apps/web or apps/worker can start.
