Kotak Neo Portfolio Dashboard 📈

A professional, production-ready Python dashboard for tracking your Kotak Securities portfolio in real-time. Built with Streamlit, this application connects to the Kotak Neo API to provide live P&L tracking, sector analytics, and visual portfolio insights.

🚀 Features

📊 Live Portfolio Hydration

• Automatically fetches live market quotes (LTP)
• Updates your portfolio value in real-time

🧠 Intelligent Caching

• Smart fallback logic
• Calculates Day's Change using OHLC data if the live feed is incomplete

📈 Visual Analytics

• Day's P&L Tracking: See exactly how much your portfolio moved today
• Sector Allocation: Interactive Donut charts showing exposure by sector
• Allocation Bar Chart: Visual breakdown of investment distribution

🔐 Secure Authentication

• Uses TOTP (Time-based OTP) for seamless 2FA login
• Credentials stored securely in a local .env file (never hardcoded)

🧱 Robust Architecture

• Modular backend design
• Separation of:
  • Authentication
  • Data Fetching
  • Analytics

📂 Project Structure

kotak-dashboard/
├── .devcontainer/       # VS Code Dev Container configuration
├── .github/workflows/   # CI/CD Pipelines
├── kotak_dashboard/     # Main Application Package
│   ├── __init__.py
│   ├── app.py           # Streamlit UI Layer
│   ├── backend.py       # Core Logic (Auth, API, Math)
│   └── cli.py           # Command-line entry point
├── tests/               # Test Suite
│   ├── conftest.py
│   ├── test_backend_analytics.py
│   └── test_backend_data.py
├── .env.example         # Template for API credentials
├── Dockerfile           # Production-ready Docker image
├── pyproject.toml       # Modern Python dependency management
└── README.md            # Documentation

🛠️ Prerequisites

Python Environment

• Python 3.11+ (Strict requirement for neo_api_client compatibility)

Kotak Neo API Credentials

You will need the following from the Kotak Neo API Portal:

• Consumer Key
• Mobile Number
• UCC (User Client Code)
• TOTP Secret Key (The alphanumeric key used to generate 2FA codes)
• MPIN

⚙️ Installation & Setup

Option 1: Standard Local Install (Recommended)

1. Clone the repository

   git clone https://github.com/yourusername/kotak-dashboard.git
   cd kotak-dashboard
   

2. Create a Virtual Environment (Python 3.11)

   # macOS/Linux
   python3.11 -m venv .venv
   source .venv/bin/activate
   
   # Windows
   py -3.11 -m venv .venv
   .venv\Scripts\activate
   

3. Install Dependencies We use pip to install the package in editable mode.

   pip install --upgrade pip
   pip install -e .
   

Option 2: Using Docker 🐳

Run the dashboard in an isolated container without installing Python locally.

1. Build the image

   docker build -t kotak-dashboard .
   

2. Run the container

   docker run -p 8501:8501 -v $(pwd)/.env:/app/.env kotak-dashboard
   

Option 3: VS Code Dev Container

1. Open the project folder in VS Code.
2. Install the Dev Containers extension.
3. Press F1 and select "Dev Containers: Reopen in Container".
4. VS Code will build a fully configured environment for you.

🧪 Running Tests

This project uses pytest for unit testing. The test suite covers:

• Authentication flows
• Data hydration logic
• Analytics calculations

Install Test Dependencies

pip install -e .[test]

🚀 CI/CD Pipeline

The project includes a GitHub Actions workflow (.github/workflows/ci_cd.yml) that automatically:

• Sets up Python 3.11
• Runs the full test suite with pytest
• Builds the Python package (Source Distribution & Wheel)
• Uploads the build artifacts to GitHub

🔑 Configuration

First Run Setup

When you run the app for the first time, a sidebar will appear asking for your credentials.

1. Enter your Consumer Key, Mobile, UCC, TOTP Secret, and MPIN.
2. Click "Save & Login".
3. This will automatically create a .env file in your project root.

Manual Setup (Optional)

Copy the example file and fill it in manually:

cp .env.example .env

Edit .env:

KOTAK_CONSUMER_KEY=your_key_here
KOTAK_MOBILE=9876543210
KOTAK_UCC=YA004
KOTAK_TOTP_SECRET=YOURSECRETKEY123
KOTAK_MPIN=123456

🏃‍♂️ Usage

Once installed, you can start the dashboard using the command line:

kotak-dashboard

Or directly via Streamlit:

streamlit run kotak_dashboard/app.py

Open your browser to http://localhost:8501 to view your portfolio.

⚠️ Disclaimer

This application is an unofficial tool built for educational and personal tracking purposes. It interacts with the Kotak Neo API but is not affiliated with Kotak Securities.

• Trading Risk: Stock market investments are subject to market risks. This tool does not provide financial advice.
• Security: Your credentials are stored locally on your machine in the .env file. Do not share this file or commit it to public repositories.

Built with ❤️ using Python & Streamlit.