# coderdojo-linz/ai-workshops architecture

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

- Interactive diagram: https://gitdiagram.com/coderdojo-linz/ai-workshops
- Repository: https://github.com/coderdojo-linz/ai-workshops

## Overview

##### Project type and purpose
- This is a multi-purpose AI Projects monorepo containing:
– A standalone Java demo (Gps-Data).
– A collection of data-driven exercises (CSV files + Markdown guides).
– A “playground” area holding:
- IaC (Terraform) to provision cloud roles and resources.
- A Next.js workshop UI with API routes that serve exercises and support a chat interface.
– A CI/CD workflow for building and publishing Docker images.

##### File structure
– Top-level components:
- Gps-Data/ (Java application)
- exercises/ (CSV data + guide markdowns for interactive data exercises)
- playground/
– iac/ (Terraform configs for Azure roles)
– workshop-ui/ (Next.js frontend + API, Dockerfile, build-utils)
– CI/CD: .github/workflows/build-publish-docker.yaml builds/pushes the Docker container(s).
– Configs: .gitignore, tsconfig.json, Dockerfile, Terraform .tf files.

##### Key insights from README
– “playground” is for non-production AI experiments (workshop UI, IaC).
– The exercises folder is static content used by the Next.js API and by offline guides.

##### Main components & relationships
a. Components:
1. Java Demo (Gps-Data) – a standalone CLI or library.
2. Exercises Data Store – raw CSV files + Markdown guides under exercises/.
3. Infra Provisioner – Terraform code in playground/iac.
4. Workshop UI – Next.js app in playground/workshop-ui.
5. CI/CD Pipeline – GitHub Actions in .github/workflows.
b. Interactions:
- The Next.js Workshop UI reads exercise metadata and CSV data from the exercises/ folder at build-time or runtime via API routes.
- The UI’s API (src/app/api/exercises and /chat) serves JSON to the React frontend and proxies requests to an LLM (system prompt + user chat).
- IaC (Terraform) provisions cloud roles/storage that the Workshop UI or backend could consume (e.g., storing logs or data).
- CI/CD builds the Workshop UI Docker image and publishes it to a container registry.
- The Java demo is independent; it’s built and run locally via its own build tool (e.g., Maven/Gradle) if integrated.
c. Architectural patterns:
- Monorepo layout separating concerns by folder.
- Next.js server-side API routes + React client for a full-stack single-page app.
- Infrastructure as Code (Terraform) for reproducible cloud setup.
- GitHub Actions for CI/CD and Docker-based deployment.
d. Key technologies:
- Java 17 (Gps-Data)
- Node.js/TypeScript, Next.js, React (Workshop UI)
- Terraform (Azure provider)
- GitHub Actions, Docker

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Developer and Repo
  Dev["Developer Workstation"]:::external
  Repo["Monorepo (Git)"]:::external
  Dev -->|push code| Repo

  %% CI/CD Pipeline
  subgraph "CI/CD Pipeline" 
    direction TB
    CI["GitHub Actions\n.build-publish-docker.yaml"]:::pipeline
    Repo -->|triggers| CI
    CI -->|build Docker image| Registry["Container Registry"]:::infra
    CI -->|publish image| Registry
  end

  %% Java Demo
  subgraph "Java Demo"
    direction TB
    Java["Gps-Data (Java 17)\nsrc/Main.java"]:::codeModule
    click Java "https://github.com/coderdojo-linz/ai-workshops/blob/main/Gps-Data/src/Main.java"
    click Java "https://github.com/coderdojo-linz/ai-workshops/blob/main/Gps-Data/.gitignore"
    click Java "https://github.com/coderdojo-linz/ai-workshops/blob/main/Gps-Data/Gps-Data.iml"
    Dev -->|local build/run| Java
  end

  %% Exercises Data Store
  Exercises["Exercises Data\nCSV + Markdown"]:::data
  click Exercises "https://github.com/coderdojo-linz/ai-workshops/blob/main/exercises/**/base-data/*.csv"
  click Exercises "https://github.com/coderdojo-linz/ai-workshops/blob/main/exercises/**/guides/*.md"
  click Exercises "https://github.com/coderdojo-linz/ai-workshops/blob/main/exercises/**/readme.md"

  %% Playground
  subgraph "Playground"
    direction TB

    subgraph "Infrastructure as Code" 
      direction TB
      IaC["Terraform Configs\nmain.tf\nvariables.tf\nazure-roles.json\n.terraform.lock.hcl"]:::infra
      click IaC "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/iac/main.tf"
      click IaC "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/iac/variables.tf"
      click IaC "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/iac/azure-roles.json"
      click IaC "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/iac/.terraform.lock.hcl"
      IaC -->|provision| Azure["Azure Resources"]:::cloud
    end

    subgraph "Workshop UI (Next.js)" 
      direction TB
      UI["Next.js App\nDockerfile\nnext.config.ts"]:::codeModule
      click UI "https://github.com/coderdojo-linz/ai-workshops/tree/main/playground/workshop-ui/Dockerfile"
      click UI "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/next.config.ts"
      UTILS["build-utils\nhash-data-files.js"]:::codeModule
      click UTILS "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/build-utils/hash-data-files.js"
      API_EX["API Route\n/src/app/api/exercises/[id]/route.ts"]:::codeModule
      click API_EX "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/app/api/exercises/[id]/route.ts"
      API_SP["API Route\n/src/app/api/exercises/[id]/system-prompt/route.ts"]:::codeModule
      click API_SP "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/app/api/exercises/[id]/system-prompt/route.ts"
      API_CHAT["API Route\n/src/app/api/chat/route.ts"]:::codeModule
      click API_CHAT "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/app/api/chat/route.ts"
      Pages["Pages\n/src/app/chat/[exercise]/page.tsx\n/src/app/workshops/page.tsx"]:::codeModule
      click Pages "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/app/chat/[exercise]/page.tsx"
      click Pages "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/app/workshops/page.tsx"
      Components["Components\nModal.tsx\nSystemPrompt.tsx"]:::codeModule
      click Components "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/components/Modal.tsx"
      click Components "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/components/SystemPrompt.tsx"
      Lib["Lib\nexercise-schema.ts\nfiles.ts\nsession.ts"]:::codeModule
      click Lib "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/lib/exercise-schema.ts"
      click Lib "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/lib/files.ts"
      click Lib "https://github.com/coderdojo-linz/ai-workshops/blob/main/playground/workshop-ui/src/lib/session.ts"

      UI --> UTILS
      UI --> API_EX
      UI --> API_SP
      UI --> API_CHAT
      UI --> Pages
      UI --> Components
      UI --> Lib
      API_EX --> Exercises
      API_SP --> Exercises
      Pages --> API_EX
      Pages --> API_CHAT
    end

  end

  %% Browser interaction
  Browser["Browser (React SPA)"]:::external
  Browser -->|HTTP| Pages
  Browser -->|HTTP| API_CHAT

  %% Registry deploy
  Registry -->|deploy image| UI
  Azure --> UI

  %% Styles
  classDef codeModule fill:#D0E8FF,stroke:#1E6EB8;
  classDef data fill:#DFFFD0,stroke:#7BAE00;
  classDef infra fill:#FFE8A0,stroke:#B88600;
  classDef pipeline fill:#FFD0D0,stroke:#B82E2E;
  classDef cloud fill:#E0F0FF,stroke:#2E6EB8;
  classDef external fill:#FFFAE0,stroke:#B88E00;
```
