# nebius-academy/llm-engineering-essentials architecture

> Architecture diagram of the GitHub repository nebius-academy/llm-engineering-essentials, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nebius-academy/llm-engineering-essentials
- Repository: https://github.com/nebius-academy/llm-engineering-essentials

## Overview

##### Project Type and Purpose
- This is an educational “course‐as‐code” repository that teaches LLM engineering through hands-on Jupyter notebooks and supporting Python modules.
- The end-to-end “NPC Factory” platform is built over six topics, incrementally covering LLM APIs, agent workflows, RAG, self-hosted LLMs, optimization, and fine-tuning.

##### File Structure
- Top‐level files: LICENSE, README.md
- Three topic directories (topic1, topic2, topic3) each containing:
- Jupyter notebooks (lessons and solutions) for interactive learning
- Python scripts (.py) implementing demo code or utilities (e.g., dungeon_navigation.py, thought_analysis.py, deep_research.py, hnsw.py, potion_shop_utils.py)
- Data assets (fantasy_items_descriptions.json, potion_shop.db, northelm.txt)
- No dedicated “frontend” or “backend” folders—this is a library of code modules invoked by notebooks.

##### Extract Architectural Insights from the README
- The course roadmap builds a platform (“NPC Factory”) through discrete projects per topic.
- Core functional goals:
a. Interact with LLM APIs (topic1)
b. Orchestrate agents and reasoning workflows (topic2)
c. Implement RAG with vector stores & databases (topic3)
- Future topics (4–6) layer self-hosting, optimization, monitoring, fine-tuning—though code for them is not in v1.

##### Main Components
a. Presentation Layer
- Jupyter Notebook Interfaces (the .ipynb files in topic1–3)
b. Application Logic Layer
- Python modules in each topic (e.g., dungeon_navigation.py, thought_analysis.py, hnsw.py, potion_shop_utils.py, deep_research.py)
c. Data Layer
- Local vector store (implemented by hnsw.py + hnsw_visualization.py)
- SQLite DB (potion_shop.db)
- Static JSON assets (fantasy_items_descriptions.json)
- Text resources (northelm.txt)
d. External Services
- Hosted LLM APIs (e.g., OpenAI, Anthropic)
- (Future) Self-hosted LLM inference endpoints

##### Relationships and Data‐Flows
- Notebooks import and invoke Python modules.
- Modules send requests to LLM APIs, receive responses, and post-process results.
- RAG modules (hnsw.py + potion_shop_utils.py) index data from JSON/DB into vector store; query vector store during reasoning.
- Results flow back to notebooks for visualization or further chaining (e.g., dungeon navigation decisions).

##### Architectural Patterns
- Layered Architecture: Presentation (Notebooks) → Business (Python modules) → Data (DB/Vector Store) → External (LLM)
- Modular Design: Each topic folder is a self-contained module teaching a specific capability
- Pipeline/Workflow Pattern: Chaining LLM prompts, agent orchestration, RAG retrieval

- Incremental build: you may overlay Topic2 components onto Topic1’s base, then Topic3 onto that, to illustrate evolution.
- Keep labels concise but descriptive: e.g., “hnsw.py (Vector Indexer),” “potion_shop.db (Context DB).”

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        T1["Topic1 Notebooks"]:::notebooks
        T2["Topic2 Notebooks"]:::notebooks
        T3["Topic3 Notebooks"]:::notebooks
    end

    %% Application Logic Layer
    subgraph "Application Logic Layer"
        DN["dungeon_navigation.py"]:::modules
        TA["thought_analysis.py"]:::modules
        DR["deep_research.py"]:::modules
        HNSW["hnsw.py (Vector Indexer)"]:::modules
        HSV["hnsw_visualization.py"]:::modules
        PSU["potion_shop_utils.py"]:::modules
    end

    %% Data Layer
    subgraph "Data Layer"
        DB["potion_shop.db"]:::data
        JSON["fantasy_items_descriptions.json"]:::data
        TXT["northelm.txt"]:::data
        VS["Vector Store"]:::data
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM APIs"]:::external
    end

    %% Relationships
    T1 -->|"prompt→response"| LLM
    T2 -->|"invoke"| DN
    T2 -->|"invoke"| TA
    DN -->|"prompt→response"| LLM
    TA -->|"prompt→response"| LLM

    T3 -->|"invoke"| DR
    T3 -->|"invoke"| HNSW
    T3 -->|"invoke"| PSU
    DR -->|"query→embeddings"| VS
    HNSW -->|"build index"| VS
    PSU -->|"ingest"| DB
    PSU -->|"ingest"| JSON
    PSU -->|"ingest"| TXT
    PSU -->|"query→embeddings"| VS
    DR -->|"prompt→response"| LLM
    PSU -->|"prompt→response"| LLM

    %% Click Events
    click T1 "https://github.com/nebius-academy/llm-engineering-essentials/tree/main/topic1/"
    click T2 "https://github.com/nebius-academy/llm-engineering-essentials/tree/main/topic2/"
    click T3 "https://github.com/nebius-academy/llm-engineering-essentials/tree/main/topic3/"
    click DN "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic2/dungeon_navigation.py"
    click TA "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic2/thought_analysis.py"
    click DR "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic3/deep_research.py"
    click HNSW "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic3/hnsw.py"
    click HSV "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic3/hnsw_visualization.py"
    click PSU "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic3/potion_shop_utils.py"
    click DB "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic3/potion_shop.db"
    click JSON "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic3/fantasy_items_descriptions.json"
    click TXT "https://github.com/nebius-academy/llm-engineering-essentials/blob/main/topic3/northelm.txt"

    %% Styles
    classDef notebooks fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef modules fill:#90EE90,stroke:#333,stroke-width:1px
    classDef data fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#DDA0DD,stroke:#333,stroke-width:1px
```
