# prd-nhat-nguyen/generative-ai-for-beginners architecture

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

- Interactive diagram: https://gitdiagram.com/prd-nhat-nguyen/generative-ai-for-beginners
- Repository: https://github.com/prd-nhat-nguyen/generative-ai-for-beginners

## Overview

##### Project type and purpose
- This is a documentation/course repository (“Generative AI For Beginners”) that uses Markdown lessons, code samples (Python, TypeScript, .NET), and Docsify to build a static website.
- It includes 21 lessons, each with “Learn” (theory) and “Build” (code samples) sections, plus multi-language support via an automated GitHub Actions translation pipeline.

##### File structure
- Top-level directories:
- 00-course-setup … 21-meta: per-lesson content with subfolders for Python, TypeScript, JavaScript, .NET, images.
- docs: contains Docsify config (index.html, _navbar.md, _sidebar.md), site assets.
- translations: holds identical lesson structure for each supported language.
- .github/workflows: CI/CD pipelines for translation, markdown validation, stale issues, welcoming.
- .devcontainer: Docker/Conda environment for local development.
- Support files: README.md (course overview), package.json/lock (Docsify dependencies), requirements.txt, environment.yml.

##### Key insights from the README
- Static site built with Docsify, hosted on GitHub Pages.
- CI/CD via GitHub Actions automates: translations, markdown linting, workflows on issues/PRs, build/deploy.
- Code samples connect to external services: Azure OpenAI Service, OpenAI API, GitHub Marketplace Models.
- Devcontainer to replicate environment locally.

a. Main components
- Content Repository (Markdown source, images, code samples)
- Translation Pipeline (GitHub Actions workflows that pull/push translations)
- Static Site Generator (Docsify + Node.js)
- CI/CD Orchestrator (GitHub Actions)
- Hosting (GitHub Pages)
- Devcontainer Environment (Docker + Conda for local preview)
- External AI Services (Azure OpenAI, OpenAI API, GitHub Models)
- Community/Support Links (Discord, Developer Forum)

b. Relationships & data flows
1. Developer pushes changes to GitHub
2. GitHub Actions “validate-markdown” → “lock” → “dependabot” → “translate” workflows run
3. Translations updated in `translations/` directory
4. Docsify build (local or CI) reads `docs/` + lesson markdown → generates static site assets
5. CI/CD deploys site to GitHub Pages (gh-pages branch)
6. End users access site via GitHub Pages URL
7. Code samples within lessons call external AI services at runtime
8. Devcontainer allows maintainers to run a local server for preview

c. Architectural patterns & design principles
- Content-as-Code (Markdown-driven content)
- Static Site Generation (Docsify)
- Monorepo Structure (all lessons & translations in one repo)
- CI/CD Pipeline (GitHub Actions for automation)
- Environment as Code (devcontainer.json + environment.yml)
- Separation of Concerns (content vs. build vs. hosting vs. translations)

d. Relevant technologies & frameworks
- Markdown, Docsify, Node.js
- GitHub Actions (YAML workflows)
- GitHub Pages (static hosting)
- Docker (devcontainer) + Conda (environment.yml)
- Python, TypeScript, .NET (code samples in lessons)
- Azure OpenAI Service, OpenAI API, GitHub Marketplace Model Catalog (runtime services)

##### Detail without overthinking
- Essential elements: content directories, build steps, translation pipeline, hosting, and runtime service interactions
- Keep translation languages represented as a single “Translations” component

## Diagram (Mermaid)

```mermaid
graph TB
    %% Subgraphs
    subgraph "Repository"
        ContentRepo["Lessons (Markdown)"]:::content
        CodeSamples["Code Samples (Python, TypeScript, .NET)"]:::content
        SupportDocs["Support & Community Docs"]:::content
    end

    subgraph "Storage"
        Translations["Translations"]:::storage
    end

    %% Core Pipeline
    CI_CD["CI/CD (GitHub Actions)"]:::pipeline
    DocsifyBuild["Docsify Build\n(Static Site Generator)"]:::content
    GitHubPages["GitHub Pages\n(Hosting)"]:::content
    Devcontainer["Devcontainer\n(Local Preview)"]:::pipeline
    EnvironmentCode["Environment-as-Code\n(requirements.yml, .env)"]:::pipeline
    ExternalAI["External AI Services\n(Azure OpenAI, OpenAI API,\nGitHub Marketplace Models)"]:::ext

    %% Relationships
    ContentRepo -->|push code| CI_CD
    CI_CD -->|run translation workflow| Translations
    CI_CD -->|build site| DocsifyBuild
    DocsifyBuild -->|deploy| GitHubPages
    Devcontainer -->|local build| DocsifyBuild
    ContentRepo -->|defines environment| EnvironmentCode
    ContentRepo --> CodeSamples
    CodeSamples -->|runtime calls| ExternalAI

    %% Click Events
    click ContentRepo "https://github.com/prd-nhat-nguyen/generative-ai-for-beginners/tree/main/00-course-setup"
    click Translations "https://github.com/prd-nhat-nguyen/generative-ai-for-beginners/tree/main/translations/en"
    click CI_CD "https://github.com/prd-nhat-nguyen/generative-ai-for-beginners/blob/main/.github/workflows/validate-markdown.yml"
    click DocsifyBuild "https://github.com/prd-nhat-nguyen/generative-ai-for-beginners/blob/main/docs/index.html"
    click Devcontainer "https://github.com/prd-nhat-nguyen/generative-ai-for-beginners/blob/main/.devcontainer/devcontainer.json"
    click EnvironmentCode "https://github.com/prd-nhat-nguyen/generative-ai-for-beginners/blob/main/requirements.txt"
    click CodeSamples "https://github.com/prd-nhat-nguyen/generative-ai-for-beginners/blob/main/06-text-generation-apps/python/aoai-app.py"
    click CodeSamples "https://github.com/prd-nhat-nguyen/generative-ai-for-beginners/blob/main/06-text-generation-apps/typescript/recipe-app/src/main.ts"

    %% Styles
    classDef content fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef storage fill:#D0F2D8,stroke:#333,stroke-width:1px
    classDef pipeline fill:#E0BBE4,stroke:#333,stroke-width:1px
    classDef ext fill:#FFE5B4,stroke:#333,stroke-width:1px
```
