added mermaid diagrams for visualization of processes

.vscode/settings.json

@@ -17,5 +17,8 @@
   ],
   "[astro]": {
     "editor.formatOnSave": false
+  },
+  "files.readonlyInclude": {
+    "{**/.c4z/.extsrcs/*.PROTSYM.cbl,**/.c4z/.extsrcs/*.PROTSYM.listing}": true
   }
 }

src/docs/README.md

@@ -0,0 +1,36 @@
+# Architecture Diagrams — README
+
+## What is Mermaid?
+
+Mermaid is a diagramming tool that lets you write diagrams as plain text inside Markdown files.
+Instead of using a visual editor, you describe the diagram in a simple syntax and it renders
+automatically in tools like GitHub, GitLab, Notion, and Obsidian.
+
+This means diagrams live alongside your code, can be version-controlled, and are easy to update
+without exporting images.
+
+## What is the C4 Model?
+
+C4 is a standard for describing software architecture through four levels of zoom, each targeting
+a different audience.
+
+- **Level 1 - Context:** The big picture. Shows your system and how it relates to users and
+  external systems. Useful for non-technical stakeholders.
+
+- **Level 2 - Container:** Zooms into your system and shows the major deployable units — apps,
+  databases, build pipelines. Useful for architects and tech leads.
+
+- **Level 3 - Component:** Zooms into a single container and shows how it is organized internally.
+  Useful for developers joining the project.
+
+- **Level 4 - Code:** The lowest level. Shows how individual files or modules relate to each other.
+  Useful when onboarding to a specific part of the codebase.
+
+## Why is it useful?
+
+Most projects grow without documentation. New developers waste time reading code just to understand
+the structure. C4 gives a shared vocabulary and a consistent way to communicate architecture at the
+right level of detail, depending on who you are talking to.
+
+These diagrams are not meant to be exhaustive. They are meant to answer the question
+"how does this system work?" as fast as possible.

src/docs/diagrams/c4level1-system-context.md

@@ -0,0 +1,28 @@
+```mermaid
+flowchart TD
+    DEV["👤 **Developer**\n──────────────\nTeam member at UXCorpRangel\nWrites code, reviews PRs,\nmanages releases"]
+
+    VISITOR["👤 **Visitor**\n──────────────\nEnd user browsing techschool.dev\nvia any modern browser"]
+
+    GH["⬜ **GitHub**\n──────────────\n« external system »\ngithub.com/UXCorpRangel/techschool-web\nSource control · PR reviews\nIssue tracking · CI/CD trigger"]
+
+    SYS["🔷 **techschool-web**\n──────────────\n« system »\nOfficial TechSchool website\nBuilt with Astro 5 + TypeScript\nOutputs fully static HTML/CSS/JS\nSEO · Sitemap · Compressed assets"]
+
+    CDN["⬜ **CDN / Hosting**\n──────────────\n« external system »\nServes pre-built static files\nglobally with low latency"]
+
+    BROWSER["⬜ **Web Browser**\n──────────────\n« external system »\nChrome · Firefox · Safari · Edge\nRenders HTML, executes client JS"]
+
+    DEV -->|"① Push commits & open PRs"| GH
+    GH -->|"② CI/CD triggers astro build\nand deploys /dist output"| SYS
+    SYS -->|"③ Built static files\ncopied to CDN origin"| CDN
+    VISITOR -->|"④ Opens browser,\nnavigates to techschool.dev"| BROWSER
+    BROWSER -->|"⑤ Fetch HTML / CSS / JS\nassets over HTTPS"| CDN
+    CDN -->|"⑥ Serve cached\nstatic response"| BROWSER
+
+    style DEV fill:#1168BD,color:#fff,stroke:#0e56a0
+    style VISITOR fill:#1168BD,color:#fff,stroke:#0e56a0
+    style SYS fill:#1168BD,color:#fff,stroke:#0e56a0
+    style GH fill:#6b6b6b,color:#fff,stroke:#444
+    style CDN fill:#6b6b6b,color:#fff,stroke:#444
+    style BROWSER fill:#6b6b6b,color:#fff,stroke:#444
+```

src/docs/diagrams/c4level2-containers.md

@@ -0,0 +1,37 @@
+```mermaid
+flowchart TD
+    DEV["👤 **Developer**\nWrites source code,\nruns pnpm scripts, commits"]
+
+    subgraph REPO["📦 techschool-web — Monorepo boundary"]
+        CFG["⚙️ **Project Config Layer**\n──────────────\nastro.config.mjs · tsconfig.json · .npmrc\n\nastro.config.mjs — registers integrations:\n  sitemap · compressor · astro-icon · seo-schema\n  sets LightningCSS as CSS transformer\n\ntsconfig.json — extends astro/tsconfigs/strict\n  defines 9 path aliases:\n  @components @ui @layouts @scripts\n  @styles @data @contracts @struct @images\n\n.npmrc — pnpm registry and install config"]
+
+        TOOL["🔧 **Dev Toolchain**\n──────────────\nESLint · ls-lint · commitlint\nlint-staged · simple-git-hooks\n\npre-commit hook:\n  → lint-staged runs ESLint --fix\n  → ls-lint checks file naming\n\ncommit-msg hook:\n  → commitlint enforces\n    Conventional Commits format\n\nAlso runnable manually:\n  pnpm lint:fix · pnpm prepare"]
+
+        SRC["🟦 **Astro Source** — src/\n──────────────\nAstro 5 + TypeScript\n\nPages · Layouts · Components\nUI primitives · Struct blocks\nClient scripts · CSS · Data\nType contracts · Images\n\nAll resolved at build time\ninto pure static output"]
+
+        DIST["📄 **Build Output** — /dist\n──────────────\nStatic HTML / CSS / JS\n\nastro build    → compiles routes\nastro-compressor → gzip + brotli\nSharp          → optimises images\nLightningCSS   → minifies CSS\n\nNo server runtime required —\nthis folder is what gets deployed"]
+    end
+
+    CDN["⬜ **CDN / Hosting**\n« external »\nServes /dist files globally"]
+    VISITOR["👤 **Visitor**\nRequests pages over HTTPS"]
+    GH["⬜ **GitHub**\n« external »\nCI/CD pipeline"]
+
+    DEV -->|"writes & edits"| SRC
+    DEV -->|"triggers via\ngit commit / pnpm"| TOOL
+    CFG -->|"integrations & aliases\nresolved at build time"| SRC
+    SRC -->|"astro build\ncompiles everything"| DIST
+    DIST -->|"deployed after build"| CDN
+    VISITOR -->|"HTTP requests"| CDN
+    DEV -->|"git push / PR"| GH
+    GH -->|"CI runs build\nand deploy"| DIST
+
+    style DEV fill:#1168BD,color:#fff,stroke:#0e56a0
+    style VISITOR fill:#1168BD,color:#fff,stroke:#0e56a0
+    style CFG fill:#2E7D32,color:#fff,stroke:#1b5e20
+    style TOOL fill:#6A1B9A,color:#fff,stroke:#4a148c
+    style SRC fill:#1168BD,color:#fff,stroke:#0e56a0
+    style DIST fill:#0277BD,color:#fff,stroke:#01579b
+    style CDN fill:#6b6b6b,color:#fff,stroke:#444
+    style GH fill:#6b6b6b,color:#fff,stroke:#444
+    style REPO fill:#f5f5f5,stroke:#bbb,color:#333
+```

src/docs/diagrams/c4level3-components.md

@@ -0,0 +1,42 @@
+```mermaid
+flowchart TD
+    subgraph SRC["Astro Source — src/"]
+        CONTRACTS["contracts/\nShared TS interfaces\nand prop types"]
+        DATA["data/\nStatic content consumed\nat build time"]
+        IMAGES["images/\nSource images optimised\nby Sharp via astro:assets"]
+        STYLES["styles/\nGlobal CSS\nprocessed by LightningCSS"]
+        SCRIPTS["scripts/\nClient-side TS\nhydrated via Astro directives"]
+        UI["components/ui/\nLow-level primitives\nButton · Card · Badge · Icon"]
+        STRUCT["components/struct/\nLayout blocks\nSection · Grid · Container"]
+        COMPONENTS["components/\nFeature components\nHero · Navbar · Footer · CourseCard"]
+        LAYOUTS["layouts/\nPage shells\nhead meta · OG · fonts · slots"]
+        PAGES["pages/\nFile-system routes\nOne file = one URL"]
+    end
+
+    CONTRACTS -->|"types for data shape"| DATA
+    CONTRACTS -->|"prop types"| COMPONENTS
+    CONTRACTS -->|"prop types"| LAYOUTS
+    DATA -->|"static content at build"| COMPONENTS
+    DATA -->|"static content at build"| PAGES
+    IMAGES -->|"optimised assets"| COMPONENTS
+    STYLES -->|"global CSS"| LAYOUTS
+    SCRIPTS -->|"client directives"| COMPONENTS
+    UI -->|"composed into"| COMPONENTS
+    STRUCT -->|"layout blocks"| COMPONENTS
+    STRUCT -->|"layout blocks"| LAYOUTS
+    COMPONENTS -->|"imported into"| LAYOUTS
+    COMPONENTS -->|"imported into"| PAGES
+    LAYOUTS -->|"wraps via slot"| PAGES
+
+    style CONTRACTS fill:#E65100,color:#fff,stroke:#bf360c
+    style DATA fill:#33691E,color:#fff,stroke:#1b5e20
+    style IMAGES fill:#4527A0,color:#fff,stroke:#311b92
+    style STYLES fill:#AD1457,color:#fff,stroke:#880e4f
+    style SCRIPTS fill:#F57F17,color:#fff,stroke:#e65100
+    style UI fill:#006064,color:#fff,stroke:#004d40
+    style STRUCT fill:#0277BD,color:#fff,stroke:#01579b
+    style COMPONENTS fill:#1168BD,color:#fff,stroke:#0e56a0
+    style LAYOUTS fill:#1565C0,color:#fff,stroke:#0d47a1
+    style PAGES fill:#283593,color:#fff,stroke:#1a237e
+    style SRC fill:#f5f5f5,stroke:#bbb,color:#333
+```

src/docs/diagrams/c4level4-code.md

@@ -0,0 +1,47 @@
+```mermaid
+flowchart TD
+    DEV["👤 Developer\ngit commit / pnpm dev / pnpm build"]
+
+    subgraph HOOKS["Git Hooks — simple-git-hooks"]
+        PRECOMMIT["pre-commit\nlint-staged + ls-lint"]
+        COMMITMSG["commit-msg\ncommitlint"]
+    end
+
+    subgraph LINTERS["Linting Tools"]
+        ESLINT["eslint.config.js\nneostandard · @stylistic · import-x\nperfectionist · astro · jsonc · yml"]
+        LSLINT[".ls-lint.yml\nkebab-case: js/ts/css/media\nPascalCase: components/layouts\nkebab-case: pages"]
+        COMMITLINT["commitlint.config.js\nConventional Commits\ntype(scope): description"]
+    end
+
+    subgraph CFGFILES["Project Configuration"]
+        PKGJSON["package.json\nscripts: dev · build · preview · lint:fix\nlint-staged targets · node>=22 · pnpm>=10"]
+        ASTROCFG["astro.config.mjs\nsitemap · compressor · icon · seo-schema\nCSS transformer: lightningcss"]
+        TSCFG["tsconfig.json\nextends astro/strict\n9 path aliases: @components @ui @layouts\n@scripts @styles @data @contracts @images"]
+        NPMRC[".npmrc\npnpm registry + hoisting\nonlyBuiltDependencies: esbuild · sharp"]
+    end
+
+    DEV -->|"git commit"| HOOKS
+    DEV -->|"pnpm lint:fix"| ESLINT
+    PKGJSON -->|"prepare script\nregisters hooks"| HOOKS
+    PKGJSON -->|"lint-staged\npoints to"| ESLINT
+    PRECOMMIT --> ESLINT
+    PRECOMMIT --> LSLINT
+    COMMITMSG --> COMMITLINT
+    ASTROCFG -->|"reads for\npath resolution"| TSCFG
+    TSCFG -->|"used by\nts-eslint parser"| ESLINT
+    NPMRC -->|"install config\nbefore deps"| PKGJSON
+
+    style DEV fill:#1168BD,color:#fff,stroke:#0e56a0
+    style PRECOMMIT fill:#6A1B9A,color:#fff,stroke:#4a148c
+    style COMMITMSG fill:#6A1B9A,color:#fff,stroke:#4a148c
+    style ESLINT fill:#C62828,color:#fff,stroke:#b71c1c
+    style LSLINT fill:#E65100,color:#fff,stroke:#bf360c
+    style COMMITLINT fill:#2E7D32,color:#fff,stroke:#1b5e20
+    style PKGJSON fill:#F57F17,color:#fff,stroke:#e65100
+    style ASTROCFG fill:#0277BD,color:#fff,stroke:#01579b
+    style TSCFG fill:#1565C0,color:#fff,stroke:#0d47a1
+    style NPMRC fill:#4527A0,color:#fff,stroke:#311b92
+    style HOOKS fill:#f3e5f5,stroke:#9c27b0,color:#333
+    style LINTERS fill:#fce4ec,stroke:#e91e63,color:#333
+    style CFGFILES fill:#e8f5e9,stroke:#4caf50,color:#333
+```