# azure-samples/js-ai-build-a-thon architecture

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

- Interactive diagram: https://gitdiagram.com/azure-samples/js-ai-build-a-thon
- Repository: https://github.com/azure-samples/js-ai-build-a-thon

## Overview

##### Project type and purpose
- This repository is not a traditional full-stack application but a “template” / tutorial orchestration system. It uses GitHub as the platform, GitHub Actions for CI/CD workflows, and Azure AI services (via the Azure AI Foundry & AI Toolkit extensions) to teach developers how to build and deploy JavaScript/TypeScript AI applications step by step.

##### File structure
- Top-level:
- `.github/steps/0-10-*.md` – sequential learning modules
- `.github/workflows/*.yml` – the pipelines that correspond to each step
- `README.md` – dynamically updated with instructions and progress
- Key patterns:
- **Orchestration**: each workflow triggers on a README change or on a push, updates the README, and moves the student to the next module.
- **Template repository**: developers instantiate their own copy (via “Start Course”), gaining a public repo with these files.
- **Azure integration points**: later steps connect to Azure AI Foundry, LangChain.js, RAG, and build an AI agent.

##### README for additional insights
- The README describes the learning journey:
1. Local AI prototype (GitHub Models + AI Toolkit)
2. Migrate to Azure AI Foundry
3. Deploy and code against Azure
4. RAG (LangChain.js)
5. Build & extend an AI agent
6. Automate with GenAIScript

##### Main components
a. **Developer workstation**
- Local code editor
- AI Toolkit + Azure AI Foundry VSCode extensions
b. **GitHub**
- Template repository
- Developer’s forked repository
- GitHub Actions (10-step pipelines)
c. **Azure Cloud**
- Azure AI Foundry (OpenAI models, embeddings, APIs)
- Optional: Azure Cognitive Search (for RAG)
d. **External libraries/services**
- GitHub Models & GenAIScript
- LangChain.js

##### Relationships and data flow
- Developer clicks “Start Course” → GitHub new repo from template
- Push to GitHub → GitHub Actions step0 → updates README with step1
- Developer follows instructions locally (AI Toolkit runs, code changes) → commit/push
→ GitHub Actions step1 → scaffolds Azure Foundry connections → update README to step2
- Repeat until final step → full AI agent deployed to Azure
- In parallel: LangChain.js + Azure Cognitive Search integrate for RAG, agent built with MCP tools

##### Architectural patterns & design principles
- **Pipeline-as-Code**: each learning step is automated by a CI workflow
- **GitOps style**: the state of the tutorial is encoded in the README and repository state
- **Modularity**: separate workflows, separate steps, clear progression
- **Extension points**: students can replace templates, adjust Azure resource definitions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    subgraph "Developer Workstation"
        DevEditor["Code Editor"]:::developer
        DevToolkit["AI Toolkit & Azure AI Foundry Extensions"]:::developer
    end

    %% GitHub Template and Repo
    subgraph "GitHub"
        TemplateRepo["Template Repository"]:::github
        ForkedRepo["Developer's Forked Repository"]:::github
        README["README.md"]:::github
        StepsFolder["Learning Modules (.github/steps/)"]:::github

        subgraph "CI/CD Workflows"
            W0["0-welcome.yml"]:::workflows
            W1["1-genai-prototype.yml"]:::workflows
            W2["2-to-azure.yml"]:::workflows
            W3["3-add-chat-ui.yml"]:::workflows
            W4["4-add-rag.yml"]:::workflows
            W5["5-frameworks.yml"]:::workflows
            W6["6-build-agent.yml"]:::workflows
            W7["7-mcp.yml"]:::workflows
            W8["8-code-review.yml"]:::workflows
            W9["9-template.yml"]:::workflows
        end
    end

    %% Azure Cloud
    subgraph "Azure Cloud"
        Foundry["Azure AI Foundry"]:::azure
        Search["Azure Cognitive Search"]:::azure
    end

    %% External Services
    subgraph "External Services"
        GitHubModels["GitHub Models & GenAIScript"]:::external
        LangChain["LangChain.js"]:::external
    end

    %% Flows
    DevEditor --> DevToolkit
    DevEditor -->|"Start Course"| TemplateRepo
    click TemplateRepo "https://github.com/azure-samples/js-ai-build-a-thon/tree/main//"
    TemplateRepo -->|"Creates New Repo"| ForkedRepo
    DevEditor -->|"push code"| ForkedRepo
    ForkedRepo -->|"push → run CI"| W0
    W0 -->|"CI → update README"| README
    README -->|"read instructions"| DevEditor

    DevEditor -->|"follow step 1 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step1"| W1
    W1 -->|"scaffold Azure connections"| README

    DevEditor -->|"follow step 2 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step2"| W2
    W2 -->|"provision Foundry"| Foundry

    DevEditor -->|"follow step 3 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step3"| W3

    DevEditor -->|"follow step 4 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step4"| W4
    W4 -->|"index data"| Search
    W4 -->|"use LangChain"| LangChain

    DevEditor -->|"follow step 5 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step5"| W5

    DevEditor -->|"follow step 6 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step6"| W6
    W6 --> Foundry

    DevEditor -->|"follow step 7 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step7"| W7

    DevEditor -->|"follow step 8 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step8"| W8

    DevEditor -->|"follow step 9 instructions & push"| ForkedRepo
    ForkedRepo -->|"run CI step9"| W9

    %% External integrations
    DevToolkit --> GitHubModels
    W2 --> AzureFoundryCall["Foundry API Calls"]:::azure
    click README "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/README.md"
    click StepsFolder "https://github.com/azure-samples/js-ai-build-a-thon/tree/main/.github/steps/"
    click W0 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/0-welcome.yml"
    click W1 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/1-genai-prototype.yml"
    click W2 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/2-to-azure.yml"
    click W3 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/3-add-chat-ui.yml"
    click W4 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/4-add-rag.yml"
    click W5 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/5-frameworks.yml"
    click W6 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/6-build-agent.yml"
    click W7 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/7-mcp.yml"
    click W8 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/8-code-review.yml"
    click W9 "https://github.com/azure-samples/js-ai-build-a-thon/blob/main/.github/workflows/9-template.yml"

    %% Styles
    classDef developer fill:#dddddd,stroke:#888888
    classDef github fill:#cce5ff,stroke:#3399ff
    classDef azure fill:#ccffcc,stroke:#33cc33
    classDef external fill:#f5e6ff,stroke:#bb33ff
    classDef workflows fill:#e6f2ff,stroke:#66b3ff,stroke-dasharray: 2 2
```
