# zamfiroiu/upb-cim architecture

> Architecture diagram of the GitHub repository zamfiroiu/upb-cim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zamfiroiu/upb-cim
- Repository: https://github.com/zamfiroiu/upb-cim

## Overview

##### Project Type and Purpose
- This repository is a static-site generator template for open educational resources (OER), built on Docusaurus.
- It provides lecture and practice content (Markdown, media, quizzes, code demos), a Docker-based build environment, and GitHub Actions workflows for linting, building, and publishing to GitHub Pages.

##### Main Components
a. Content Source
- “content/” folder: chapters subdivided into “lecture/” (slides, demos, media, quizzes) and “lab/” or “practice/” sections.
- “config.yaml”: Docusaurus site configuration (title, URL, base URL, social links).
- Common utility Makefiles and support code under “content/common/” for building demos and tests.
b. Build Environment
- Dockerfile: defines the builder image with Node.js, Docusaurus, reveal-md, MarkdownPP, Make.
- Local development: run Docker container mounting “/content” and “/output” to build and preview.
- Makefile recipes (in each chapter) that invoke MarkdownPP, reveal-md, and Docusaurus build steps.
c. CI/CD Pipeline (GitHub Actions)
- `.github/workflows/super-linter.yml`: static analysis of Markdown and code.
- `.github/workflows/deployment.yml`: on push to main or tagged commits, builds the site inside Docker, then deploys to the `gh-pages` branch.
- Workflow config files in `.github/workflows/config/` and rules in `.github/workflows/rules/` for lint customization.
d. Hosting and Delivery
- gh-pages branch: holds generated static files.
- GitHub Pages: serves the static site at `https://<username>.github.io[/<repo>]`.
- End-users (students, instructors) access via web browser.

##### Relationships and Data Flows
1. Author edits Markdown, code demos, media in the “content/” tree locally.
2. Changes are committed & pushed to GitHub.
3. GitHub Actions triggers:
- Lint job validates Markdown and code.
- Build job: spins up Docker container → runs Makefiles → invokes MarkdownPP + reveal-md for slides, then Docusaurus build to produce static HTML/CSS/JS in `_site/`.
- Deploy job pushes `_site/` output to `gh-pages` branch.
4. GitHub Pages serves the live site. Users view the static site in their browsers.

##### Architectural Patterns and Principles
- Static Site Generation (SSG): content-as-code, no runtime backend.
- Containerization: isolated, reproducible build environment via Docker.
- GitOps / CI-as-code: full build & deploy pipeline defined in version control.
- Modular content structure: chapters, lectures, labs all follow the same folder conventions.

##### Detailed Elements
- Source Control (GitHub repo)
- CI Jobs (Lint, Build, Deploy)
- Docker Builder (Dockerfile, mounted volumes)
- Build Tools (Make, MarkdownPP, reveal-md, Docusaurus)
- Output (`_site/`, `gh-pages` branch)
- Hosting (GitHub Pages)
- Clients (Web browsers)

##### Final Recommendations
1. Logical summary (Content → Build → Deploy → Serve)
2. Expanded view of the Build stage showing Docker + Make + Docusaurus.
- Avoid extraneous detail; focus on the CI/CD pipeline, static-site generation, and hosting path as the core architecture.

## Diagram (Mermaid)

```mermaid
flowchart TB
  subgraph "Source Repository"
    SR["GitHub Repo"]:::source
    CS["Content Source (content/)"]:::source
    LC["Chapter Lecture (content/chapters/template-chapter/lecture/)"]:::source
    LB["Chapter Lab/Practice (content/chapters/template-chapter/lab/)"]:::source
    CU["Common Build Utilities (content/common/)"]:::source
    CFG["Docusaurus Config (config.yaml)"]:::source
    RM["Repository Docs (README.md, CONTRIBUTING.md, COPYING.md, REVIEWING.md)"]:::source
  end
  SR -->|"git push"| Lint
  CS --> SR
  LC --> SR
  LB --> SR
  CU --> SR
  CFG --> SR
  RM --> SR

  subgraph "CI/CD Pipeline"
    Lint["CI Lint Job"]:::pipeline
    subgraph "Lint Configuration"
      R["Lint Rules (.github/workflows/rules/)"]:::pipeline
      C["Lint Config (.github/workflows/config/config.json)"]:::pipeline
    end
    Build["CI Build Job"]:::pipeline
    Deploy["CI Deploy Job"]:::pipeline
  end
  Lint -->|"uses rules & config"| R
  Lint -->|"uses rules & config"| C
  Lint -->|"on push triggers"| Build
  Build -->|"on success"| Deploy

  subgraph "Build Stage"
    DB["Docker Build Environment (Dockerfile)"]:::build
    TOOLS["Build Tools (Make, MarkdownPP, reveal-md, Docusaurus)"]:::build
    OUTPUT["Static Site Output (_site/)"]:::deploy
  end
  Build -->|"runs container"| DB
  DB -->|"executes build tools"| TOOLS
  TOOLS -->|"generates static site"| OUTPUT

  OUTPUT -->|"push output"| Deploy
  Deploy -->|"push to gh-pages"| GHBranch["gh-pages branch"]:::deploy
  GHBranch -->|"served by"| GHPages["GitHub Pages"]:::deploy
  GHPages -->|"HTTP request"| Browser["Web Browser (Students/Instructors)"]:::user

  click CS "https://github.com/zamfiroiu/upb-cim/tree/main/content/"
  click LC "https://github.com/zamfiroiu/upb-cim/tree/main/content/chapters/template-chapter/lecture/"
  click LB "https://github.com/zamfiroiu/upb-cim/tree/main/content/chapters/template-chapter/lab/"
  click CU "https://github.com/zamfiroiu/upb-cim/tree/main/content/common/"
  click CFG "https://github.com/zamfiroiu/upb-cim/blob/main/config.yaml"
  click RM "https://github.com/zamfiroiu/upb-cim/blob/main/README.md"
  click Lint "https://github.com/zamfiroiu/upb-cim/blob/main/.github/workflows/super-linter.yml"
  click R "https://github.com/zamfiroiu/upb-cim/tree/main/.github/workflows/rules/"
  click C "https://github.com/zamfiroiu/upb-cim/blob/main/.github/workflows/config/config.json"
  click Build "https://github.com/zamfiroiu/upb-cim/blob/main/.github/workflows/deployment.yml"
  click DB "https://github.com/zamfiroiu/upb-cim/tree/main/Dockerfile"
  click TOOLS "https://github.com/zamfiroiu/upb-cim/tree/main/content/common/makefile/"
  click TOOLS "https://github.com/zamfiroiu/upb-cim/tree/main/content/chapters/template-chapter/lecture/Makefile"

  classDef source fill:#D0E8FF,stroke:#0969DA,color:#0969DA;
  classDef pipeline fill:#FFEDD5,stroke:#D97706,color:#A44A28;
  classDef build fill:#FFF7ED,stroke:#F59E0B,color:#B45309;
  classDef deploy fill:#D1FAE5,stroke:#059669,color:#065F46;
  classDef user fill:#E5E7EB,stroke:#6B7280,color:#374151;
```
