Invester

Automated paper trading platform for Indian equities (NSE/BSE). Build stock screeners, create automated investment plans, and simulate trades — all with virtual money.

⚠️ This is a paper-trading-only application. No real money is involved. No broker accounts are required. All portfolio values are simulated.

Key Facts

• India-only: Targets NSE and BSE equities
• Paper trading only: No real orders are placed, no broker credentials needed
• AI mode is optional: Disabled by default. The app is fully functional without any AI API keys or external accounts
• No external API accounts needed to run locally — the skeleton runs without FMP, Upstox, or any data provider

Tech Stack

• Framework: Next.js 14 (App Router)
• Language: TypeScript (strict mode)
• Styling: Tailwind CSS
• Database: PostgreSQL 16 (via Prisma ORM)
• Package Manager: pnpm 9+
• Testing: Vitest

Prerequisites

• Node.js 18+
• pnpm 9+
• Docker & Docker Compose (for local PostgreSQL)

Local Setup

# 1. Install dependencies
pnpm install

# 2. Start the database
docker compose up -d

# 3. Copy environment config (all defaults work — no API keys needed)
cp .env.example .env

# 4. Generate Prisma client
pnpm exec prisma generate

# 5. Run database migrations
pnpm exec prisma migrate dev

# 6. Seed the database (instruments, fundamentals, price bars, holidays, demo user)
pnpm db:seed

# 7. Start the dev server
pnpm dev

The app will be available at http://localhost:3000.

Scripts

Script	Description
pnpm dev	Start development server
pnpm build	Production build
pnpm start	Start production server
pnpm lint	Run ESLint
pnpm typecheck	TypeScript type checking
pnpm test	Run tests (Vitest)
pnpm db:generate	Generate Prisma client
pnpm db:migrate	Run database migrations
pnpm db:seed	Seed the database with demo data
pnpm format	Format code with Prettier

Project Structure

src/
├── app/                  # Next.js App Router pages and layouts
│   ├── layout.tsx        # Root layout with paper-trading banner
│   ├── page.tsx          # Landing page
│   └── globals.css       # Tailwind + CSS custom properties
├── lib/
│   ├── money.ts          # BigInt paise arithmetic (no floats for money)
│   ├── money.test.ts     # 28 tests including path-independence proof
│   ├── config.ts         # Zod-validated config from env vars
│   ├── db.ts             # Prisma client singleton
│   └── providers/        # Provider abstraction layer
│       ├── types.ts      # Domain data shapes (all money as bigint)
│       ├── index.ts      # Interfaces + registry factory
│       ├── instruments/  # Instrument universe provider
│       ├── pricebars/    # Historical OHLCV provider
│       ├── quotes/       # Current price provider (EOD default)
│       ├── fundamentals/ # PE, ROE, market cap etc.
│       ├── screener/     # Filter + sort engine
│       ├── news/         # News feed (null by default)
│       ├── ai/           # AI decisions (disabled by default)
│       ├── execution/    # Simulated fill engine with Indian fees
│       └── notifications/# Console + DB notification provider
prisma/
├── schema.prisma         # 23 models, 16 enums
├── seed.ts               # Idempotent CSV-based seeder
├── data/                 # CSV seed files (65 instruments, 16k+ price bars)
└── README.md             # Schema documentation

Seed Data

The database seeds include:

• 65 real NSE symbols with sector/industry classification
• Fundamental data (PE, ROE, market cap, etc.) for all 65 instruments
• 16,250 synthetic OHLCV bars (250 trading days × 65 symbols)
• 18 NSE holidays for 2026
• Demo user with a ₹10,00,000 paper trading account

Design Docs

Detailed design documentation lives in the invester-docs/ directory adjacent to this project:

• 03-architecture.md — Tech stack, module breakdown, deployment
• 04-data-model-and-api.md — Database schema, API routes
• 05-ui-design.md — UI spec, design tokens, accessibility
• 06-design-review.md — Design review findings
• 06a-critical-fixes.md — Critical defect fixes (cost basis, path-independence)
• 07-provider-abstraction.md — Provider interfaces and adapter design

Money Handling

All monetary calculations use integer paise as bigint — never floating-point numbers. This prevents rounding errors that would corrupt P&L calculations over time. See src/lib/money.ts for the implementation and rationale.

The proportionalCostRelief function guarantees path-independent P&L: selling shares in any sequence of partial lots produces the same total cost relief as selling all at once.