# 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**

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

2. **Create a Virtual Environment (Python 3.11)**

   ```bash
   # 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.

   ```bash
   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**

   ```bash
   docker build -t kotak-dashboard .
   ```

2. **Run the container**

   ```bash
   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
```bash
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:

```bash
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:

```bash
kotak-dashboard
```

Or directly via Streamlit:

```bash
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.
