# shraddharai412/eightfold.ai_assesment_company_research_ai_assistant architecture

> Architecture diagram of the GitHub repository shraddharai412/eightfold.ai_assesment_company_research_ai_assistant, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant
- Repository: https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant

## Overview

##### Project Type and Purpose
- This is a full-stack, Python-based research assistant application.
- It exposes a Streamlit frontend (ui/) and a tightly-coupled backend orchestrator (core/) to gather real-time data, drive an LLM, and generate business-grade account plans.
- No persistent database—data flows from external sources (Yahoo Finance, Google News, Wikipedia, Gemini) through the Research Engine into the UI.

##### File Structure
- Top level
– app.py: entry point for Streamlit
– requirements.txt / config/keys.env: dependency list and API key storage
- core/ (research_engine + service wrappers)
– research_engine.py: orchestrator
– llm_client.py: Gemini API wrapper
– *_service.py: one file per external data source (ticker, Yahoo, news, wiki)
- plan/
– plan_generator.py: initial 8-section plan creation via Gemini
– plan_updater.py: modifies specific plan sections on user requests
- ui/
– layout.py, components.py, theme.py: Streamlit layout, theming, reusable UI bits
– assets/: static files (bot avatar)
- utils/
– logger.py: centralized debug logging
– text_cleaner.py: normalizes and sanitizes incoming text

##### Inspect the README for Architecture Insights
- Data-flow pseudocode: User Input → ResearchEngine.run() → PlanGenerator.generate() → Rendered in Sidebar → PlanUpdater → UI.
- Tech stack: Python 3.12, Streamlit, yfinance, RSS, Wikipedia API, Gemini 2.0 Flash.

##### Main Components
a. Streamlit Frontend (ui/)
b. Research Engine (core/research_engine.py)
c. Service Adapters
- Ticker Service → Yahoo Search Wrapper
- Yahoo Service → Company financials
- News Service → Google News RSS
- Wiki Service → Wikipedia API
d. LLM Client (Gemini)
e. Plan Modules (plan_generator, plan_updater)
f. Utilities (text_cleaner, logger)
g. Configuration Store (config/keys.env)
h. External Systems (Yahoo Finance, Google News, Wikipedia, Gemini API)

##### Relationships and Data Flow
- User → Streamlit UI → calls Research Engine
- Research Engine
– invokes Ticker Service → retrieves ticker
– parallel calls: Yahoo Service, News Service, Wiki Service
- Aggregated data → LLM Client → generates 8-section plan
- Plan → returned to UI for display
- User edits → Plan Updater modifies existing plan structure → UI updates

##### Architectural Patterns and Principles
- Orchestrator Pattern: core/research_engine.py coordinates all services
- Separation of Concerns: each service in its own module
- Pipeline / Chain-of-Responsibility: sequential data gathering → LLM → plan generation
- Environment-driven Configuration: config/keys.env for secrets

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    user["User"]:::external

    %% Streamlit Frontend
    subgraph "Streamlit Frontend"
        app["app.py"]:::frontend
        uiLayout["layout.py"]:::frontend
        uiComp["components.py"]:::frontend
        uiTheme["theme.py"]:::frontend
        uiAssets["assets/"]:::frontend
    end

    %% Research Engine Core
    subgraph "Research Engine (core)"
        re["research_engine.py"]:::core
        ticker["ticker_service.py"]:::core
        yahoo["yahoo_service.py"]:::core
        news["news_service.py"]:::core
        wiki["wiki_service.py"]:::core
        llm["llm_client.py"]:::llm
    end

    %% Plan Modules
    subgraph "Plan Modules"
        gen["plan_generator.py"]:::llm
        upd["plan_updater.py"]:::llm
    end

    %% Utilities & Config
    subgraph "Utilities & Config"
        logger["logger.py"]:::util
        cleaner["text_cleaner.py"]:::util
        config["keys.env"]:::util
        req["requirements.txt"]:::util
    end

    %% External Systems
    subgraph "External Systems"
        yfin["Yahoo Finance"]:::external
        gnews["Google News RSS"]:::external
        wikiAPI["Wikipedia API"]:::external
        geminiAPI["Gemini API"]:::external
    end

    %% Data Flow
    user --> app
    app --> re
    re --> ticker
    re --> yahoo
    re --> news
    re --> wiki
    ticker --> yfin
    yahoo --> yfin
    news --> gnews
    wiki --> wikiAPI
    re --> llm
    llm --> geminiAPI
    llm --> gen
    gen --> app
    app --> upd
    upd --> app

    %% Utility & Config Usage
    re -->|uses| logger
    re -->|uses| cleaner
    llm -->|reads API key| config

    %% Click Events
    click app "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/app.py"
    click uiLayout "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/ui/layout.py"
    click uiComp "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/ui/components.py"
    click uiTheme "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/ui/theme.py"
    click uiAssets "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/tree/main/ui/assets/"
    click re "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/core/research_engine.py"
    click ticker "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/core/ticker_service.py"
    click yahoo "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/core/yahoo_service.py"
    click news "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/core/news_service.py"
    click wiki "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/core/wiki_service.py"
    click llm "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/core/llm_client.py"
    click gen "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/plan/plan_generator.py"
    click upd "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/plan/plan_updater.py"
    click logger "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/utils/logger.py"
    click cleaner "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/utils/text_cleaner.py"
    click config "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/config/keys.env"
    click req "https://github.com/shraddharai412/eightfold.ai_assesment_company_research_ai_assistant/blob/main/requirements.txt"

    %% Styles
    classDef frontend fill:#D6EAF8,stroke:#2980B9
    classDef core fill:#D5F5E3,stroke:#27AE60
    classDef external fill:#FCF3CF,stroke:#F1C40F
    classDef llm fill:#E8DAEF,stroke:#8E44AD
    classDef util fill:#E5E8E8,stroke:#566573
```
