BlackLedger

BlackLedger is an AI forensic-research platform for Indian smallcap equities. It combines deterministic forensic signals, a retrieval-backed multi-agent runtime, and a feed-first product UX for fundamental analysis and regulatory surveillance.

Regulatory posture: Research platform only. Not investment advice. SEBI RA registration: Application in progress unless SEBI_RA_REGISTRATION_NUMBER is configured.

Architecture Overview

Three-Layer Forensic Model

1. Deterministic Signals (lib/forensics/*)

   • Pure modules: pledge spike, auditor churn, RPT ratio, earnings quality, dilution, options anomaly, peer divergence
   • Outputs: ForensicSignal records aggregated by scoring.ts

2. Knowledge Layer

   • RuntimeMemory + pgvector embeddings (via Fireworks)
   • Entity graph: RuntimeEntityEdge, RuntimeContradiction
   • Persistent claim tracking: Claim, ClaimEvidence

3. Narrative Layer

   • LangGraph agent mesh with parallel execution
   • TRIAGE agent plans → Specialists run in parallel (4 agents, staggered launch)
   • DEVILS_ADVOCATE + SCRIBE synthesize findings
   • Claim-linked evidence + memo linting (scribeLinter.ts)

Agent Runtime Pipeline (lib/agents/)

Orchestrator (detects EventType from mission)
  ↓
Runtime (graph.v2.ts)
  ├─ TRIAGE: Plans which specialists to run
  ├─ SPECIALIST MESH: Parallel execution (staggered by FIREWORKS_AGENT_DELAY_MS)
  │  └─ Bounded concurrency (enforced in fireworks.ts)
  ├─ DEVILS_ADVOCATE: Challenges findings
  └─ SCRIBE: Synthesizes memo + claims

Outputs persist as AgentStep records → Claims synced via lib/intelligence/claims.ts

Data Sources & Integrations

Primary: BSE (BseIndiaApi)

• Market data, OHLCV, fundamentals for screeners and agents
• Shareholding data via lib/bse-data.ts

Secondary: NSE

• Bhavcopy (EOD price data) via lib/nse/ingest.ts
• Equity master, shareholding via parsers

Enrichment: Yahoo Finance

• OHLCV fallback, technical indicators (lib/indicators.ts)
• Agent-accessible tools in lib/agents/runtime/tools.ts

Sentiment: Marketaux

• India news + sentiment (100/day limit)
• Replaces Finnhub (failed on Indian stocks)

Portfolio: Upstox

• Reserved for portfolio/trade execution
• NOT used as primary market data source

Core Tech Stack

Layer	Technology
Framework	Next.js 14 App Router + TypeScript
Auth	WorkOS AuthKit (lib/auth/server.ts)
Database	Postgres + Prisma + pgvector + Neon serverless driver adapter
LLM	Fireworks API (DeepSeek-V4-Flash default, V4-Pro escalation)
Agent Runtime	LangGraph + Fireworks
Background Jobs	Inngest (event-driven, replaces Bull + Redis)
Embeddings	Fireworks embeddings into pgvector
Observability	Sentry, PostHog, Axiom, Pino
Payments	Razorpay (mock mode in dev)
Email	Resend (transactional)
Web Push	VAPID keys + browser Notification API
Deployment	Vercel (region: bom1 / Mumbai)

Product Surfaces

Feature	Route	Purpose
Feed	/feed	Curated signal-triggered events
Watchlist	/watchlist	Tracked companies + alerts
Screener	/screener	Multi-signal filtering + ranking
Company Deep-Dive	/company/[ticker]	Full forensic report + chat
Portfolio	/portfolio	Holdings + Upstox sync
Calls & Memos	/calls, /memos	Trade ideas + research docs
Analyst Chat	/company/[ticker]/chat	Multi-turn conversation with runtime
Settings	/settings/notifications	Notification preferences
Institutional API	/api/v1/*	API-key auth + entitlements + rate limits
Admin Console	/admin/*	Users, runs, signals, billing, audit
Analyst Console	/claims	Claim review & verification

Running Locally

Setup

npm install
# Copy .env.example → .env and configure:
#   DATABASE_URL (Postgres)
#   FIREWORKS_API_KEY (LLM)
#   WORKOS_* (auth)
#   RAZORPAY_* (payments)
#   RESEND_API_KEY (email)
#   VAPID_* (web push)

Development

npm run dev              # Next.js dev server (localhost:3000)
npm run inngest:dev      # Inngest Dev Server (for background jobs) — run in parallel
npm run build            # prisma generate && next build
npm run lint             # eslint (not enforced in builds)

Database

npm run db:push          # Apply schema changes (no migration file)
npm run prisma:migrate   # Create versioned migration + apply
npm run prisma:generate  # Regenerate Prisma client

Testing & Validation

npm test                           # vitest run (all tests)
npm run test:watch                 # vitest watch
npx vitest run -t "pattern"        # run matching tests
npm run agent:e2e                  # Agent runtime smoke test
npm run eval:runtime               # Runtime quality evaluation
npm run check                      # Health-check script

Admin Scripts

npm run db:push                    # Sync schema to database
scripts/backfill-nse-history.ts    # Populate NSE price history
scripts/ingest-bse-universe.ts     # Backfill BSE company universe

Conventions

• Path alias: @/* → repo root (tsconfig.json + vitest.config.ts)
• ESLint: Ignored during builds — run npm run lint manually
• Ad-hoc scripts: *.ts files at repo root (run via tsx <file>)
• Throwaway code: scratch/ directory
• Environment: Build command on Vercel: prisma generate && next build
• LLM routing:
  • Flash (default): DeepSeek-V4-Flash for all calls (cost-optimized)
  • Pro: DeepSeek-V4-Pro only for escalation (document your reason)

Key Files & Modules

File/Dir	Purpose
lib/agents/orchestrator.ts	Entry point: detects event type, dispatches to runtime
lib/agents/runtime/graph.v2.ts	LangGraph state machine + parallel mesh
lib/agents/runtime/tools.ts	Agent tool definitions (web search, data fetch, etc.)
lib/agents/scribeLinter.ts	Validates claim evidence & memo structure
lib/forensics/*	Signal modules (pledge, auditor, RPT, etc.)
lib/ai/fireworks.ts	Fireworks API client + routing logic
lib/ai/embeddings.ts	Vector generation + pgvector insert
lib/auth/server.ts	WorkOS AuthKit + user sync
lib/bse-data.ts	BSE data fetch + cache
lib/data-fetchers/	Unified data ingestion facade
lib/inngest/functions/	Background job handlers
lib/intelligence/claims.ts	Claim persistence from agent outputs
lib/entitlements/	Subscription tier → feature mapping
middleware.ts	CSRF, auth gates, API key validation
prisma/schema.prisma	~39 models: users, runs, signals, claims, etc.

Deployment

• Platform: Vercel
• Region: bom1 (Mumbai)
• Build: prisma generate && next build
• Environment: Managed via Vercel project settings
• Database: Neon serverless Postgres (Prisma driver adapter)

Notes

• The root README.md was last updated May 2026. See CLAUDE.md for authoritative architecture guidance.
• No longer used: Mistral LLM, NextAuth, Bull + Redis, Finnhub, Clerk
• Current stack: Fireworks (DeepSeek), WorkOS, Inngest, BSE, Marketaux