# anupbaranwal/learn-buddy-ai architecture

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

- Interactive diagram: https://gitdiagram.com/anupbaranwal/learn-buddy-ai
- Repository: https://github.com/anupbaranwal/learn-buddy-ai

## Overview

##### Project type and purpose
- Learn-Buddy-AI is a Python-based, full-stack (CLI) multi-agent generative AI system whose purpose is to automatically produce personalized study materials (summaries, flashcards, quizzes) for any topic. It’s built as a Kaggle intensive capstone project and runs as a command-line application.

##### File structure
Top-level:
- requirements.txt – dependency list
- src/capstone/config/config.py & topics.json – configuration constants and topic definitions
- src/capstone/agents/ – each file defines one agent in the workflow
– aggregator_agent.py
– controller_agent.py
– flash_card_agent.py
– parallel_agent.py
– quiz_agent.py
– root_agent.py
– summary_agent.py
Patterns:
- Modular “agent” classes under a single package
- A controller agent orchestrates the overall flow
- A parallel agent to spawn summary/flashcard/quiz agents concurrently
- An aggregator agent to merge outputs

##### README for additional insights
- Workflow: User → Search Agent → Parallel Agents (Summary, Flashcard, Quiz, Weakness) → Aggregator → Final Study Pack
- No persistent storage yet; CLI only
- Future enhancements: database, adaptive pathways

a. Main components:
1. User Interface (CLI Entrypoint)
2. ControllerAgent (Orchestrator)
3. SearchAgent / RootAgent (Topic fetcher)
4. ParallelAgent (Concurrency manager)
5. Worker Agents:
– SummaryAgent
– FlashCardAgent
– QuizAgent
– [WeaknessAgent placeholder]
6. AggregatorAgent (Combines outputs)
7. Config/Data Store: config.py, topics.json
8. External AI Service (OpenAI / Gemini, etc.)

b. Relationships & Data Flow:
- CLI → ControllerAgent: accepts subject/topic input
- ControllerAgent → Root/SearchAgent: fetch raw content
- ControllerAgent → ParallelAgent: spin off worker agents simultaneously
- ParallelAgent → Summary/Flashcard/Quiz Agents: each calls external AI API
- Worker Agents → return generated content → AggregatorAgent
- AggregatorAgent → produces final Study Pack → CLI displays

c. Architectural Patterns & Principles:
- Modular multi-agent pattern: single-responsibility agents
- Orchestrator + worker concurrency (ParallelAgent)
- Config-driven design (topics.json, config.py)
- Future extensibility: plug in new agents (e.g., recommendation_agent)

d. Key Technologies & Frameworks:
- Python 3.x
- OpenAI/Gemini API (via requests or openai client)
- JSON for topic definitions
- Standard concurrency modules (asyncio or threading inside ParallelAgent)

##### Diagramming Recommendations
1. User → ControllerAgent
2. ControllerAgent → RootAgent → (parallel fork) → Summary/Flashcard/Quiz Agents
3. Worker Agents → AggregatorAgent → CLI output
- Blue = orchestration (ControllerAgent, ParallelAgent)
- Green = worker agents (SummaryAgent, FlashCardAgent, QuizAgent, AggregatorAgent)
- Orange = external dependencies (AI API)
- Gray = config/data

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLI["User CLI Entrypoint"]:::interface
    ControllerAgent["ControllerAgent\n(aggregator_agent.py)"]:::orchestration
    RootAgent["RootAgent\n(root_agent.py)"]:::orchestration
    ParallelAgent["ParallelAgent\n(parallel_agent.py)"]:::orchestration
    SummaryAgent["SummaryAgent\n(summary_agent.py)"]:::worker
    FlashCardAgent["FlashCardAgent\n(flash_card_agent.py)"]:::worker
    QuizAgent["QuizAgent\n(quiz_agent.py)"]:::worker
    WeaknessAgent["WeaknessAgent\n(placeholder)"]:::worker
    AggregatorAgent["AggregatorAgent\n(aggregator_agent.py)"]:::worker
    Config["Config\n(config.py)"]:::config
    Topics["Topics\n(topics.json)"]:::config
    ExternalAI["External AI Service"]:::external

    CLI -->|"input topic"| ControllerAgent
    ControllerAgent -->|"fetch content"| RootAgent
    ControllerAgent -->|"spawn workers"| ParallelAgent

    RootAgent --> ParallelAgent

    ParallelAgent -->|"generate_summary() "| SummaryAgent
    ParallelAgent -->|"generate_flashcards() "| FlashCardAgent
    ParallelAgent -->|"generate_quiz() "| QuizAgent
    ParallelAgent -->|"generate_weakness() "| WeaknessAgent

    SummaryAgent -->|"API call"| ExternalAI
    FlashCardAgent -->|"API call"| ExternalAI
    QuizAgent -->|"API call"| ExternalAI
    WeaknessAgent -->|"API call"| ExternalAI

    ExternalAI --> SummaryAgent
    ExternalAI --> FlashCardAgent
    ExternalAI --> QuizAgent
    ExternalAI --> WeaknessAgent

    SummaryAgent -->|"return content"| AggregatorAgent
    FlashCardAgent -->|"return content"| AggregatorAgent
    QuizAgent -->|"return content"| AggregatorAgent
    WeaknessAgent -->|"return content"| AggregatorAgent

    AggregatorAgent -->|"compile study pack"| CLI

    Config -.-> ControllerAgent
    Topics -.-> ControllerAgent

    click CLI "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/README.md"
    click CLI "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/requirements.txt"
    click ControllerAgent "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/agents/controller_agent.py"
    click RootAgent "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/agents/root_agent.py"
    click ParallelAgent "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/agents/parallel_agent.py"
    click SummaryAgent "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/agents/summary_agent.py"
    click FlashCardAgent "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/agents/flash_card_agent.py"
    click QuizAgent "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/agents/quiz_agent.py"
    click AggregatorAgent "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/agents/aggregator_agent.py"
    click Config "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/config/config.py"
    click Topics "https://github.com/anupbaranwal/learn-buddy-ai/blob/main/src/capstone/topics.json"

    classDef orchestration fill:#D0E7FF,stroke:#333,stroke-width:1px
    classDef worker fill:#D0FFD6,stroke:#333,stroke-width:1px
    classDef external fill:#FFD8A8,stroke:#333,stroke-width:1px
    classDef config fill:#E0E0E0,stroke:#333,stroke-width:1px
    classDef interface fill:#BEEFFF,stroke:#333,stroke-width:1px
```
