# devansh-236/kite_portfolio-ai-assistant architecture

> Architecture diagram of the GitHub repository devansh-236/kite_portfolio-ai-assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/devansh-236/kite_portfolio-ai-assistant
- Repository: https://github.com/devansh-236/kite_portfolio-ai-assistant

## Overview

##### Project type and purpose
- This is an open-source, CLI-driven multi-agent Python application for personalized portfolio analysis.
- It orchestrates a sequence of AI “agents” (preference collection, data fetching, analysis, suggestion, reporting) to produce Markdown reports.
- It integrates with two external services: Zerodha Kite Connect API (portfolio data) and Google Gemini AI (analysis).

##### File structure
- Top-level scripts & configs:
– main.py: the orchestrator/entrypoint
– Makefile: setup, test, run commands
– requirements.txt / .env.example: dependency & environment management
- Packages:
– agents/: one file per agent (single-responsibility modules)
– config/: settings.py reads environment variables
– kite_api/: connector.py wraps Kite Connect API calls
– utils/: api_handler.py (rate-limited Gemini calls) and auth.py (Kite token setup)
- Output directories (not in your tree but implied by README): reports/ and user_preferences/ for generated artifacts

##### Key architectural hints from the README
- Multi-Agent pipeline: UserPreference → PortfolioFetcher → DataAnalyzer → SuggestionEngine → ReportGenerator
- Config and authentication handled up-front (env vars, utils/auth.py)
- External API interactions abstracted into dedicated modules
- Reports saved locally in Markdown, user preferences saved as JSON

##### Main components & their relationships
1) CLI Orchestrator (main.py & Makefile commands)
2) Config Manager (config/settings.py)
3) Auth Module (utils/auth.py)
4) Agents (agents/):
– UserPreferenceAgent
– PortfolioFetcherAgent
– DataAnalyzerAgent
– SuggestionEngineAgent
– ReportGeneratorAgent
5) Kite Connect API (external service)
6) Google Gemini AI API (external service)
7) Utilities (utils/api_handler.py)
8) Local Storage: user_preferences/ (JSON), reports/ (Markdown)

b. Interactions & data flow:
- Startup: CLI Orchestrator reads config → sets up env via config/settings.py
- Auth step: utils/auth.py ↔ Kite Connect API to obtain access token
1. UserPreferenceAgent ↔ (local JSON in user_preferences/)
2. PortfolioFetcherAgent → kite_api/connector.py → Kite Connect API → returns portfolio data
3. DataAnalyzerAgent → utils/api_handler.py → Gemini AI API → enriched analysis results
4. SuggestionEngineAgent (uses analysis + preferences) → output suggestions
5. ReportGeneratorAgent → writes Markdown to reports/

c. Architectural patterns & principles:
- Agent or pipeline pattern—each agent has a single responsibility
- Layered architecture:
– Presentation/Orchestration layer: main.py, Makefile
– Configuration layer: config/settings.py, .env
– Integration layer: kite_api/connector.py, utils/api_handler.py, utils/auth.py
– Domain layer: agents/ modules
– Persistence: local file storage (JSON/MD)
- Dependency inversion: modules use abstracted connectors and handlers rather than raw HTTP calls
- Rate-limiting, retry, and error-handling are encapsulated in utils/api_handler and connector

d. Key technologies & libraries:
- Python 3.10+
- Zerodha Kite Connect Python client (via kite_api/connector.py)
- Google Gemini AI HTTP API (via utils/api_handler.py)
- dotenv or environs for config/settings.py
- Makefile for reproducible commands
- Markdown for report outputs

## Diagram (Mermaid)

```mermaid
graph TD
    %% Orchestration Layer
    Orchestrator["CLI Orchestrator\n(main.py & Makefile)"]:::internal
    Makefile["Makefile Commands"]:::internal

    %% Configuration & Auth
    ConfigMgr["Config Manager\n(config/settings.py)"]:::internal
    AuthMod["Auth Module\n(utils/auth.py)"]:::utility

    %% Agent Pipeline
    UPAgent["UserPreferenceAgent\n(agents/preference_agent.py)"]:::internal
    PFAgent["PortfolioFetcherAgent\n(agents/fetcher_agent.py)"]:::internal
    DAAgent["DataAnalyzerAgent\n(agents/analyzer_agent.py)"]:::internal
    SEAgent["SuggestionEngineAgent\n(agents/suggestion_agent.py)"]:::internal
    RGAgent["ReportGeneratorAgent\n(agents/report_agent.py)"]:::internal

    %% Integration Layer
    Connector["Kite Connect API Connector\n(kite_api/connector.py)"]:::utility
    APIHandler["Google Gemini AI Handler\n(utils/api_handler.py)"]:::utility

    %% External Services
    KiteAPI["Kite Connect API"]:::external
    GeminiAPI["Google Gemini AI API"]:::external

    %% Local Storage
    PrefStorage["user_preferences/\n(JSON)"]:::storage
    ReportStorage["reports/\n(Markdown)"]:::storage

    %% Flow
    Orchestrator -->|reads config| ConfigMgr
    Orchestrator -->|Make commands| Makefile
    ConfigMgr -->|env vars| AuthMod
    AuthMod -->|obtain token| Connector

    Connector -->|HTTP/JSON| KiteAPI

    ConfigMgr -->|settings| UPAgent
    UPAgent -->|read/write JSON| PrefStorage

    UPAgent --> PFAgent
    PFAgent -->|fetch portfolio| Connector
    PFAgent --> PFAgentData

    PFAgent --> DAAgent

    DAAgent -->|analyze data| APIHandler
    APIHandler -->|HTTP/JSON| GeminiAPI
    APIHandler --> DAAgent

    DAAgent --> SEAgent
    SEAgent --> RGAgent
    RGAgent -->|write MD| ReportStorage

    %% Click Events
    click Orchestrator "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/main.py"
    click Makefile "https://github.com/devansh-236/kite_portfolio-ai-assistant/tree/main/Makefile"
    click ConfigMgr "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/config/settings.py"
    click AuthMod "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/utils/auth.py"
    click UPAgent "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/agents/preference_agent.py"
    click PFAgent "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/agents/fetcher_agent.py"
    click DAAgent "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/agents/analyzer_agent.py"
    click SEAgent "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/agents/suggestion_agent.py"
    click RGAgent "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/agents/report_agent.py"
    click Connector "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/kite_api/connector.py"
    click APIHandler "https://github.com/devansh-236/kite_portfolio-ai-assistant/blob/main/utils/api_handler.py"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef utility fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#98FB98,stroke:#333,stroke-width:1px
    classDef storage fill:#FFFACD,stroke:#333,stroke-width:1px
```
