# ashushekar/maven_code architecture

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

- Interactive diagram: https://gitdiagram.com/ashushekar/maven_code
- Repository: https://github.com/ashushekar/maven_code

## Overview

##### Project Type and Purpose
- This is a Python-based, full-stack curriculum/demo application that teaches LangChain/LangGraph concepts through week-by-week agent workflows.
- It exposes a Gradio UI (frontend) and a CLI entry point that drives various “week” modules (backend), orchestrating chat agents, retrieval patterns, and tool integrations.

##### File Structure
- Top-level “code/” directory houses:
- run.py – CLI launcher for different weeks/parts
- requirements.txt – dependency list
- perplexia_ai/ – main package
- Inside perplexia_ai/:
- app.py – Gradio wiring & factory dispatch logic
- core/ – abstract ChatInterface and shared chat logic
- tools/ – reusable LangChain-compatible utilities (e.g., calculator)
- week1/, week2/, week3/ – progressively complex agent implementations
- docs/ – system_architecture.drawio, PDFs, markdown walkthrough
- Configuration: .python-version, .gitignore, and environment variables (for OpenAI, Tavily, MCP credentials).

##### README Insights
- Describes multi-week capabilities: prompting foundations, RAG, agentic workflows
- Highlights factory pattern (`create_chat_implementation` per week)
- Mentions external services: OpenAI chat models, Tavily search, PDF storage, optional MCP servers

##### Main Components
a. Presentation Layer
– run.py CLI launcher
– Gradio server (app.py) with endpoints and UI components
b. Orchestration Layer
– WeekFactory module in app.py (dispatches to week1/2/3 modules)
– ChatInterface abstraction (core/chat_interface.py)
c. Business Logic Layer (Week Modules)
– week1/: Prompting, stateful memory, calculator tool
– week2/: Retrieval workflows (web + PDF RAG)
– week3/: Agentic workflows, research graphs, bookmarking MCP server
d. Utilities Layer
– tools/: reusable utilities invoked by agents (e.g., calculator.py)
e. Data & Docs
– Local PDF docs in docs/ (used for RAG)
– bookmarks.json (week3 persistent state)
f. External Services
– OpenAI (chat completions)
– Tavily (live web search)
– MCP Server (bookmarking)

##### Relationships and Data Flows
- run.py → Gradio UI → API handlers in app.py
- UI handlers call WeekFactory.create_chat_implementation(week, part)
- Chat implementation invokes ChatInterface methods, leveraging core abstractions
- Agents call utilities in tools/ and retrieval routines in week modules
- Retrieval agents read local PDFs or call Tavily, merge evidence
- Agents issue OpenAI API requests for LLM responses
- week3 agents may call an external MCP bookmarking service (HTTP)
- Responses stream back through the factory to the Gradio frontend

##### Architectural Patterns & Design Principles
- Layered Architecture: clear separation between UI, orchestration, business logic, utilities, and external services
- Factory Pattern: week-based dispatch in app.py
- Dependency Injection: ChatInterface and tool modules plugged into agents
- Modular Plugin-style Weeks: each week is a self-contained folder with consistent API

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Frontend Layer
    subgraph "Frontend Layer"
        CLI["run.py CLI Launcher"]:::frontend
        UI["Gradio Server"]:::frontend
    end

    %% Orchestration Layer
    subgraph "Orchestration Layer"
        Factory["WeekFactory Dispatch"]:::orches
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        subgraph "Week1"
            W1Fact["Week1 Factory"]:::business
            W1Mod["Week1 Modules"]:::business
        end
        subgraph "Week2"
            W2Fact["Week2 Factory"]:::business
            W2Mod["Week2 Modules"]:::business
        end
        subgraph "Week3"
            W3Fact["Week3 Factory"]:::business
            W3Mod["Week3 Modules"]:::business
        end
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        CI["ChatInterface Abstraction"]:::util
        CL["Core Chat Logic"]:::util
        CT["Calculator Tool"]:::util
    end

    %% Data & Docs
    subgraph "Data & Docs"
        PDFs["Local PDF Docs"]:::data
        Book["bookmarks.json"]:::data
        Req["requirements.txt"]:::data
    end

    %% External Services
    subgraph "External Services"
        OA["OpenAI API"]:::external
        Tav["Tavily Search"]:::external
        MCP["MCP Bookmark Server"]:::external
    end

    %% Connections
    CLI --> UI
    UI --> Factory
    Factory --> W1Fact
    Factory --> W2Fact
    Factory --> W3Fact
    W1Fact --> W1Mod
    W2Fact --> W2Mod
    W3Fact --> W3Mod
    W1Mod --> CI
    W1Mod --> CT
    W2Mod --> PDFs
    W2Mod --> Tav
    W3Mod --> MCP
    W3Mod --> Book
    W1Mod --> OA
    W2Mod --> OA
    W3Mod --> OA
    CI --> CL

    %% Click Events
    click CLI "https://github.com/ashushekar/maven_code/blob/main/code/run.py"
    click UI "https://github.com/ashushekar/maven_code/blob/main/code/perplexia_ai/app.py"
    click Factory "https://github.com/ashushekar/maven_code/blob/main/code/perplexia_ai/app.py"
    click W1Fact "https://github.com/ashushekar/maven_code/blob/main/code/perplexia_ai/week1/factory.py"
    click W2Fact "https://github.com/ashushekar/maven_code/blob/main/code/perplexia_ai/week2/factory.py"
    click W3Fact "https://github.com/ashushekar/maven_code/blob/main/code/perplexia_ai/week3/factory.py"
    click CI "https://github.com/ashushekar/maven_code/blob/main/code/perplexia_ai/core/chat_interface.py"
    click CL "https://github.com/ashushekar/maven_code/tree/main/code/perplexia_ai/core/"
    click CT "https://github.com/ashushekar/maven_code/blob/main/code/perplexia_ai/tools/calculator.py"
    click W1Mod "https://github.com/ashushekar/maven_code/tree/main/code/perplexia_ai/week1/"
    click W2Mod "https://github.com/ashushekar/maven_code/tree/main/code/perplexia_ai/week2/"
    click W3Mod "https://github.com/ashushekar/maven_code/tree/main/code/perplexia_ai/week3/"
    click PDFs "https://github.com/ashushekar/maven_code/tree/main/code/perplexia_ai/docs/"
    click Book "https://github.com/ashushekar/maven_code/blob/main/code/perplexia_ai/week3/bookmarks.json"
    click Req "https://github.com/ashushekar/maven_code/blob/main/code/requirements.txt"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef orches fill:#90EE90,stroke:#000,stroke-width:1px
    classDef business fill:#FFFACD,stroke:#000,stroke-width:1px
    classDef util fill:#FFDAB9,stroke:#000,stroke-width:1px
    classDef data fill:#FFE4E1,stroke:#000,stroke-width:1px
    classDef external fill:#F08080,stroke:#000,stroke-width:1px
```
