# 54g0/kriar-learning-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/54g0/kriar-learning-assistant
- Repository: https://github.com/54g0/kriar-learning-assistant

## Overview

##### Project Type & Purpose
- This is a single-repository, Python‐based web application built with Streamlit.
- It delivers a context-aware AI learning assistant: you load a YouTube video, extract its transcript, pick a timestamp, and ask questions that the AI answers using that exact context.

##### High-Level Architecture Components
A. Frontend (UI)
- app.py (Streamlit application): defines pages (“Load Video,” “Q&A Chat,” “Code Assistant”), handles user inputs, session state, and displays results.
B. Core Business Logic
- context_extractor.py: fetches YouTube transcripts, slices them by timestamp.
- agent.py: orchestrates a LangGraph workflow—pulls context, reformulates the user’s query, invokes the model, post-processes results.
- model.py: adapter layer for AI providers (OpenAI, Groq, Google AI), exposes a uniform interface for chat/completion calls.
- tools.py: auxiliary toolset (e.g., Wikipedia search) that the agent can invoke when needed.
C. External Services
- YouTube API (transcript source).
- AI Model Providers: OpenAI, Groq, Google AI APIs.
- Wikipedia API (via tools.py).
D. Session & Storage
- Streamlit’s in-memory session state holds video URLs, raw transcripts, selected timestamp, and chat history—no external database.

##### Key Interactions & Data Flows
1. User enters a YouTube URL → Frontend calls context_extractor → YouTube API → Transcript returned → stored in session state → UI confirms success.
2. User selects timestamp + asks a question → Frontend passes (query, timestamp) to agent → Agent fetches relevant transcript slice from session state via context_extractor → Agent sends “prompt + context” to model.py → model.py calls the chosen AI provider → Response flows back to agent → UI.
3. In “Code Assistant,” the UI sends raw code snippet + instruction to agent → agent invokes model.py directly (and optionally tools.py) → answer displayed.

##### Architectural Patterns & Design Principles
- Adapter Pattern (model.py abstracts multiple AI backends).
- Orchestration Pattern (agent.py organizes the workflow steps using LangGraph).
- Separation of Concerns: UI (app.py) vs. Context Extraction vs. Model Invocation vs. External Tools.
- Plugin/Extension Points:
- A new AI provider by extending model.py.
- New toolbox routines in tools.py.

##### Essential Elements Checklist
[ ] Clear, descriptive labels on each component
[ ] Flow numbering for major use cases

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend (Streamlit UI)"
        UI["app.py"]:::frontend
        ASSETS["Static Assets"]:::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic"
        CE["context_extractor.py"]:::logic
        AG["agent.py"]:::logic
        MOD["model.py"]:::logic
        TO["tools.py"]:::logic
        SUB_NEW_PROVIDER["+ New Provider"]:::logic
        SUB_NEW_TOOL["+ New Tool"]:::logic
    end

    %% External Services
    subgraph "External Services"
        YT["YouTube API"]:::external
        AI["AI Providers"]:::external
        WIKI["Wikipedia API"]:::external
    end

    %% Session Storage
    SF(("Session State")):::storage

    %% Main Flows
    UI -->|1 video URL| CE
    CE -->|"transcript"| SF
    SF -->|"stored transcript"| UI

    UI -->|2 timestamp + query| AG
    AG -.->|fetch context| SF
    AG -->|"AI prompt/response"| MOD
    MOD -->|"calls provider"| AI
    AI -->|"model response"| MOD
    AG -->|"wiki query/response"| TO
    TO -->|"wiki data"| AG
    AG -->|"response"| UI

    UI -->|3 code snippet + instruction| AG
    AG -->|"AI prompt/response"| MOD

    %% Stubs for extensibility
    MOD --> SUB_NEW_PROVIDER
    TO --> SUB_NEW_TOOL

    %% Click Events
    click UI "https://github.com/54g0/kriar-learning-assistant/blob/main/app.py"
    click CE "https://github.com/54g0/kriar-learning-assistant/blob/main/context_extractor.py"
    click AG "https://github.com/54g0/kriar-learning-assistant/blob/main/agent.py"
    click MOD "https://github.com/54g0/kriar-learning-assistant/blob/main/model.py"
    click TO "https://github.com/54g0/kriar-learning-assistant/blob/main/tools.py"
    click ASSETS "https://github.com/54g0/kriar-learning-assistant/tree/main/assets/"

    %% Styles
    classDef frontend fill:#D6EFFF,stroke:#000;
    classDef logic fill:#DFFFD6,stroke:#000;
    classDef external fill:#FFE6B3,stroke:#000;
    classDef storage fill:#FFF3D6,stroke:#000,stroke-dasharray: 5 5;
    
    %% Legend
    subgraph Legend
        A["Box = Code Module"]:::logic
        B["Cylinder = In-Memory Store"]:::storage
        C["Box = External Service"]:::external
        D["Box = Frontend"]:::frontend
    end
```
