# wangz30/ai-agents-for-beginners architecture

> Architecture diagram of the GitHub repository wangz30/ai-agents-for-beginners, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wangz30/ai-agents-for-beginners
- Repository: https://github.com/wangz30/ai-agents-for-beginners

## Overview

##### Project Type and Purpose
- This is a **static content course** repository (a “docs + code samples” site), not a front-end/backend web app.
- It bundles **11 lessons**: each lesson has Markdown pages and Python Jupyter notebooks demonstrating AI Agent frameworks.
- It supports **multi-language translations** via GitHub Actions and provides a reproducible dev environment via a `.devcontainer`.

##### Main Components
A. **GitHub Repository**
- Stores all content:
- `README.md`, `images/`, `00-course-setup/…`, `01-intro-to-ai-agents/…`, …
- `code_samples` (Jupyter notebooks) under each lesson.
- `translations/` folders for each language.
- CI/CD workflows under `.github/workflows`.
- Dev environment under `.devcontainer`.
B. **Developer Environment**
- VS Code Codespaces / local VS Code using `.devcontainer/Dockerfile` and `devcontainer.json`.
- Runs `requirements.txt` to install Python, Semantic Kernel, AutoGen, Azure AI Agent Service SDKs.
C. **CI/CD Pipeline (GitHub Actions)**
- **validate-markdown**: checks broken links, formatting.
- **co-op-translator**: syncs source Markdown to translation folders.
- **welcome-issue**, **welcome-pr**: community engagement.
- Triggers on pushes, PRs, and scheduled translation updates.
D. **Translation Service**
- Automated GitHub Action job invokes a translation engine (could be Azure Translator or co-op bot).
- Synchronizes updates into `translations/<lang>/…`.
E. **Content Hosting / Publication**
- (Optionally) GitHub Pages or Docs site.
- Static Markdown rendered for end-users.
F. **External AI Services**
- **Azure AI Foundry** endpoints
- **GitHub Model Catalog** endpoints
- Embedded sample code in notebooks calls these REST/SDK interfaces.
G. **External Resources & Community**
- Discord server, YouTube videos, Microsoft docs links.
- Contributors open issues/PRs; CLA workflow ensures compliance.

##### Relationships & Data Flows
- Developer clones/forks → opens in Codespace (.devcontainer) → edits Markdown/notebooks → pushes to GitHub.
- GitHub push → CI workflows:
- validate-markdown → status check
- co-op-translator → updates translations
- on merge → translations updated / site rebuilt.
- End-users browse lessons:
- static pages served from GitHub or local clone.
- run Jupyter notebooks locally, which spin up Python kernel → calls Azure AI Foundry & GitHub Model Catalog to demonstrate agent frameworks.
- Community contributions funnel back via issues/PRs.

##### Architectural Patterns & Principles
- **Content Repository Pattern**: Treat documentation as code; versioned, reviewed, built via CI.
- **Reproducible Dev Environments**: `.devcontainer` ensures every contributor has the same Docker-based environment.
- **CI-driven Localization**: Translation is automated via a pipeline, not manual file copying.
- **Modular Lesson Design**: Each lesson folder is self-contained (Markdown + samples + assets).
- **Separation of Concerns**:
- Content vs. Code samples
- Dev environment vs. CI/CD vs. Runtime demos
- Source vs. Translations

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Users
    Developer["Developer"]:::env
    EndUser["End-User"]:::env

    %% GitHub Repository
    subgraph "GitHub Repository (Content & Structure)"
        Repo["GitHub Repo"]:::repo
        README["README.md"]:::repo
        Images["images/"]:::repo
        CourseSetup["00-course-setup/"]:::repo
        Lesson1["01-intro-to-ai-agents/"]:::repo
        Lesson2["02-explore-agentic-frameworks/"]:::repo
        LessonN["11-mcp/"]:::repo
        Translations["translations/"]:::repo
        SupportFiles["CODE_OF_CONDUCT.md, LICENSE, SECURITY.md, SUPPORT.md"]:::repo
    end

    %% Developer Environment
    subgraph "Developer Environment (Devcontainer)"
        DevcontainerDocker[".devcontainer/Dockerfile"]:::env
        DevcontainerJSON[".devcontainer/devcontainer.json"]:::env
        Requirements["requirements.txt"]:::env
        EnvExample[".env.example"]:::env
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline (GitHub Actions)"
        Validate["validate-markdown.yml"]:::pipeline
        Translator["co-op-translator.yml"]:::pipeline
        WelcomeIssue["welcome-issue.yml"]:::pipeline
        WelcomePR["welcome-pr.yml"]:::pipeline
    end

    %% Translation Service
    subgraph "Translation Service"
        TransEngine["Translation Engine"]:::pipeline
        TranslatedContent["translations/<lang>/…"]:::repo
    end

    %% Lesson Content Modules
    subgraph "Lesson Content Modules"
        LS00["00-course-setup/"]:::content
        LS01["01-intro-to-ai-agents/"]:::content
        LS02["02-explore-agentic-frameworks/"]:::content
    end

    %% External AI Services
    subgraph "External AI Services"
        AzureFoundry["Azure AI Foundry"]:::external
        GitHubModel["GitHub Model Catalog"]:::external
    end

    %% Community & Support Channels
    subgraph "Community & Support Channels"
        Discord["Discord / YouTube / MS Docs"]:::community
        Issues["Issue & PR Templates"]:::community
    end

    %% Flows
    Developer -->|clones| Repo
    Developer -->|opens in Codespace| DevcontainerDocker
    DevcontainerDocker --> Requirements
    Requirements -->|installs| DevcontainerDocker
    Developer -->|edits content| LS01
    Developer -->|git push| Repo

    Repo -->|trigger| Validate
    Validate -->|on success| Translator
    Translator -->|invoke| TransEngine
    TransEngine -->|sync| TranslatedContent
    Repo -->|trigger| WelcomeIssue
    Repo -->|trigger| WelcomePR

    EndUser -->|browse static pages| Repo
    EndUser -->|run notebooks| LS01
    LS01 -->|SDK calls| AzureFoundry
    LS02 -->|SDK calls| GitHubModel

    %% Click Events
    click Repo "https://github.com/wangz30/ai-agents-for-beginners/blob/main/README.md"
    click README "https://github.com/wangz30/ai-agents-for-beginners/blob/main/README.md"
    click Images "https://github.com/wangz30/ai-agents-for-beginners/tree/main/images/"
    click CourseSetup "https://github.com/wangz30/ai-agents-for-beginners/tree/main/00-course-setup/"
    click Lesson1 "https://github.com/wangz30/ai-agents-for-beginners/tree/main/01-intro-to-ai-agents/"
    click Lesson2 "https://github.com/wangz30/ai-agents-for-beginners/tree/main/02-explore-agentic-frameworks/"
    click LessonN "https://github.com/wangz30/ai-agents-for-beginners/tree/main/11-mcp/"
    click Translations "https://github.com/wangz30/ai-agents-for-beginners/tree/main/translations/"
    click SupportFiles "https://github.com/wangz30/ai-agents-for-beginners/blob/main/CODE_OF_CONDUCT.md"
    click DevcontainerDocker "https://github.com/wangz30/ai-agents-for-beginners/tree/main/.devcontainer/Dockerfile"
    click DevcontainerJSON "https://github.com/wangz30/ai-agents-for-beginners/blob/main/.devcontainer/devcontainer.json"
    click Requirements "https://github.com/wangz30/ai-agents-for-beginners/blob/main/requirements.txt"
    click EnvExample "https://github.com/wangz30/ai-agents-for-beginners/blob/main/.env.example"
    click Validate "https://github.com/wangz30/ai-agents-for-beginners/blob/main/.github/workflows/validate-markdown.yml"
    click Translator "https://github.com/wangz30/ai-agents-for-beginners/blob/main/.github/workflows/co-op-translator.yml"
    click WelcomeIssue "https://github.com/wangz30/ai-agents-for-beginners/blob/main/.github/workflows/welcome-issue.yml"
    click WelcomePR "https://github.com/wangz30/ai-agents-for-beginners/blob/main/.github/workflows/welcome-pr.yml"
    
    %% Styles
    classDef repo fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef env fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef pipeline fill:#dcedc8,stroke:#33691e,color:#33691e;
    classDef content fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef external fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef community fill:#f5f5f5,stroke:#616161,color:#616161;
```
