From 6d85f9e2c5c40beeb7803ddab9d93b79164648c9 Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:26:45 -0300 Subject: [PATCH 1/9] added C4 containers --- .vscode/settings.json | 3 ++ src/docs/diagrams/c4level1-system-context.mmd | 17 ++++++++++ src/docs/diagrams/c4level2-containers.mmd | 23 +++++++++++++ src/docs/diagrams/c4level3-components.mmd | 32 +++++++++++++++++ src/docs/diagrams/c4level4-code.mmd | 34 +++++++++++++++++++ 5 files changed, 109 insertions(+) create mode 100644 src/docs/diagrams/c4level1-system-context.mmd create mode 100644 src/docs/diagrams/c4level2-containers.mmd create mode 100644 src/docs/diagrams/c4level3-components.mmd create mode 100644 src/docs/diagrams/c4level4-code.mmd diff --git a/.vscode/settings.json b/.vscode/settings.json index 834a55f..cb9ee01 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -17,5 +17,8 @@ ], "[astro]": { "editor.formatOnSave": false + }, + "files.readonlyInclude": { + "{**/.c4z/.extsrcs/*.PROTSYM.cbl,**/.c4z/.extsrcs/*.PROTSYM.listing}": true } } diff --git a/src/docs/diagrams/c4level1-system-context.mmd b/src/docs/diagrams/c4level1-system-context.mmd new file mode 100644 index 0000000..32b597e --- /dev/null +++ b/src/docs/diagrams/c4level1-system-context.mmd @@ -0,0 +1,17 @@ +C4Context + title System Context — techschool-web + + Person(visitor, "Visitor", "User browsing the TechSchool website") + Person(dev, "Developer", "Team member maintaining the codebase") + + System(techschool, "techschool-web", "Official TechSchool website built with Astro. Serves static HTML/CSS/JS with SEO, sitemaps, and compressed assets.") + + System_Ext(browser, "Web Browser", "Chrome, Firefox, Safari, etc.") + System_Ext(github, "GitHub", "Source control, issue tracking\ngithub.com/UXCorpRangel/techschool-web") + System_Ext(cdn, "CDN / Hosting", "Serves the built static site to end users") + + Rel(visitor, browser, "Visits the site") + Rel(browser, cdn, "Fetches static assets") + Rel(cdn, techschool, "Hosts built output") + Rel(dev, github, "Push commits, open PRs") + Rel(github, techschool, "CI/CD triggers build pipeline") diff --git a/src/docs/diagrams/c4level2-containers.mmd b/src/docs/diagrams/c4level2-containers.mmd new file mode 100644 index 0000000..1014732 --- /dev/null +++ b/src/docs/diagrams/c4level2-containers.mmd @@ -0,0 +1,23 @@ +C4Container + title Container Diagram — techschool-web + + Person(dev, "Developer") + Person(visitor, "Visitor") + + System_Boundary(project, "techschool-web Monorepo") { + Container(src, "Astro Source", "Astro + TypeScript", "Pages, layouts, components, scripts, styles, and static data") + Container(build, "Build Output /dist", "Static HTML/CSS/JS", "Optimised, compressed output produced by astro build") + Container(toolchain, "Dev Toolchain", "Node.js / pnpm scripts", "ESLint, ls-lint, commitlint, lint-staged, simple-git-hooks — enforces code quality on every commit") + Container(config, "Project Config", "astro.config.mjs, tsconfig.json, .npmrc", "Wires together integrations, path aliases, compiler options, and registry settings") + } + + System_Ext(cdn, "CDN / Hosting") + System_Ext(github, "GitHub") + + Rel(dev, src, "Writes components, pages, styles") + Rel(dev, toolchain, "Triggers via git hooks and pnpm scripts") + Rel(src, config, "Reads aliases and Astro integrations at build time") + Rel(src, build, "astro build compiles to static files") + Rel(build, cdn, "Deployed and served") + Rel(visitor, cdn, "Requests pages and assets") + Rel(toolchain, github, "Enforces commit message convention before push") diff --git a/src/docs/diagrams/c4level3-components.mmd b/src/docs/diagrams/c4level3-components.mmd new file mode 100644 index 0000000..1aa3536 --- /dev/null +++ b/src/docs/diagrams/c4level3-components.mmd @@ -0,0 +1,32 @@ +# C4 Level 3 — Component + +```mermaid +C4Component + title Component Diagram — Astro Source + + Container_Boundary(src, "src/") { + Component(pages, "src/pages/", "Astro pages (kebab-case)", "File-system routes. Each .astro file becomes an HTML page.") + Component(layouts, "src/layouts/", "Astro layouts (PascalCase)", "Shared page shells — wrap pages with common head, header, footer.") + Component(components, "src/components/", "Astro components (PascalCase)", "Feature components consumed by pages and layouts.") + Component(ui, "src/components/ui/", "UI primitives (PascalCase)", "Reusable low-level Astro components: buttons, cards, etc.") + Component(struct, "src/components/struct/", "Structural components (PascalCase)", "Higher-order layout blocks: sections, grids.") + Component(scripts, "src/scripts/", "Client-side TS (kebab-case)", "Browser JS hydrated by Astro. Uses Embla Carousel.") + Component(styles, "src/styles/", "CSS (kebab-case)", "Global styles. LightningCSS processes them at build time.") + Component(data, "src/data/", "TS data files (kebab-case)", "Static content/config consumed at build time.") + Component(contracts, "src/contracts/", "TS types (kebab-case)", "Shared TypeScript interfaces and type contracts.") + Component(images, "src/images/", "Images (kebab-case)", "Source images processed by Sharp via astro:assets.") + } + + Rel(pages, layouts, "Extends / wraps via slot") + Rel(pages, components, "Imports feature components") + Rel(layouts, components, "Imports structural components") + Rel(components, ui, "Composes UI primitives") + Rel(components, struct, "Uses structural blocks") + Rel(components, scripts, "Client:load / client:idle scripts") + Rel(components, styles, "Imports global and scoped CSS") + Rel(pages, data, "Imports static data at build time") + Rel(components, data, "Reads data for rendering") + Rel(contracts, data, "Types consumed by data files") + Rel(contracts, components, "Types imported for props") + Rel(components, images, "Via astro:assets with Sharp optimisation") +``` diff --git a/src/docs/diagrams/c4level4-code.mmd b/src/docs/diagrams/c4level4-code.mmd new file mode 100644 index 0000000..d97f86c --- /dev/null +++ b/src/docs/diagrams/c4level4-code.mmd @@ -0,0 +1,34 @@ +# C4 Level 4 — Code (Config & Toolchain wiring) + +```mermaid +C4Component + title Code-level Diagram — Configuration & Toolchain + + Container_Boundary(cfg, "Configuration Files") { + Component(astrocfg, "astro.config.mjs", "Astro config", "Registers integrations: sitemap, compressor, icon, seo-schema. Sets LightningCSS as CSS transformer.") + Component(tscfg, "tsconfig.json", "TypeScript config", "Extends astro/tsconfigs/strict. Defines path aliases: @components, @ui, @layouts, @scripts, @styles, @data, @contracts, @struct, @images.") + Component(npmrc, ".npmrc", "pnpm config", "Sets registry and any pnpm-specific options.") + Component(pkgjson, "package.json", "Project manifest", "Declares scripts (dev, build, preview, lint:fix), git hooks config via simple-git-hooks, and lint-staged file patterns.") + } + + Container_Boundary(tools, "Toolchain Files") { + Component(eslint, "eslint.config.js", "ESLint flat config", "Chains: neostandard, @stylistic, import-x, perfectionist, astro, jsonc, yml, package-json parsers and rules.") + Component(lslint, ".ls-lint.yml", "ls-lint config", "Enforces kebab-case for JS/TS/CSS/media files. Enforces PascalCase for .astro components and layouts. kebab-case for pages.") + Component(commitlint, "commitlint.config.js", "commitlint config", "Extends @commitlint/config-conventional — enforces Conventional Commits on every commit message.") + } + + Container_Boundary(hooks, "Git Hooks (simple-git-hooks)") { + Component(precommit, "pre-commit hook", "shell", "Runs lint-staged (ESLint --fix on staged files) then ls-lint (file naming check).") + Component(commitmsg, "commit-msg hook", "shell", "Runs commitlint to validate commit message format.") + } + + Rel(pkgjson, eslint, "lint:fix script invokes ESLint") + Rel(pkgjson, precommit, "simple-git-hooks registers pre-commit") + Rel(pkgjson, commitmsg, "simple-git-hooks registers commit-msg") + Rel(precommit, eslint, "lint-staged calls ESLint") + Rel(precommit, lslint, "ls-lint validates file names") + Rel(commitmsg, commitlint, "validates message against conventional commits") + Rel(astrocfg, tscfg, "Astro reads tsconfig for path resolution") + Rel(tscfg, eslint, "ESLint uses typescript-eslint parser with tsconfig") + Rel(npmrc, pkgjson, "pnpm reads registry settings before install") +``` From 29e2b2ab334006aa34b6514019ea7cb5c31abd49 Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:30:52 -0300 Subject: [PATCH 2/9] readability of mermaid diagrams --- src/docs/diagrams/c4level1-system-context.mmd | 39 ++++++--- src/docs/diagrams/c4level2-containers.mmd | 64 +++++++++----- src/docs/diagrams/c4level3-components.mmd | 81 +++++++++++------- src/docs/diagrams/c4level4-code.mmd | 85 ++++++++++++------- 4 files changed, 174 insertions(+), 95 deletions(-) diff --git a/src/docs/diagrams/c4level1-system-context.mmd b/src/docs/diagrams/c4level1-system-context.mmd index 32b597e..69e4895 100644 --- a/src/docs/diagrams/c4level1-system-context.mmd +++ b/src/docs/diagrams/c4level1-system-context.mmd @@ -1,17 +1,30 @@ -C4Context - title System Context — techschool-web +# C4 Level 1 — System Context - Person(visitor, "Visitor", "User browsing the TechSchool website") - Person(dev, "Developer", "Team member maintaining the codebase") +```mermaid +flowchart TD + DEV["👤 **Developer**\n──────────────\nTeam member at UXCorpRangel\nWrites code, reviews PRs,\nmanages releases"] - System(techschool, "techschool-web", "Official TechSchool website built with Astro. Serves static HTML/CSS/JS with SEO, sitemaps, and compressed assets.") + VISITOR["👤 **Visitor**\n──────────────\nEnd user browsing techschool.dev\nvia any modern browser"] - System_Ext(browser, "Web Browser", "Chrome, Firefox, Safari, etc.") - System_Ext(github, "GitHub", "Source control, issue tracking\ngithub.com/UXCorpRangel/techschool-web") - System_Ext(cdn, "CDN / Hosting", "Serves the built static site to end users") + GH["⬜ **GitHub**\n──────────────\n« external system »\ngithub.com/UXCorpRangel/techschool-web\nSource control · PR reviews\nIssue tracking · CI/CD trigger"] - Rel(visitor, browser, "Visits the site") - Rel(browser, cdn, "Fetches static assets") - Rel(cdn, techschool, "Hosts built output") - Rel(dev, github, "Push commits, open PRs") - Rel(github, techschool, "CI/CD triggers build pipeline") + 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 +``` diff --git a/src/docs/diagrams/c4level2-containers.mmd b/src/docs/diagrams/c4level2-containers.mmd index 1014732..96bfc22 100644 --- a/src/docs/diagrams/c4level2-containers.mmd +++ b/src/docs/diagrams/c4level2-containers.mmd @@ -1,23 +1,41 @@ -C4Container - title Container Diagram — techschool-web - - Person(dev, "Developer") - Person(visitor, "Visitor") - - System_Boundary(project, "techschool-web Monorepo") { - Container(src, "Astro Source", "Astro + TypeScript", "Pages, layouts, components, scripts, styles, and static data") - Container(build, "Build Output /dist", "Static HTML/CSS/JS", "Optimised, compressed output produced by astro build") - Container(toolchain, "Dev Toolchain", "Node.js / pnpm scripts", "ESLint, ls-lint, commitlint, lint-staged, simple-git-hooks — enforces code quality on every commit") - Container(config, "Project Config", "astro.config.mjs, tsconfig.json, .npmrc", "Wires together integrations, path aliases, compiler options, and registry settings") - } - - System_Ext(cdn, "CDN / Hosting") - System_Ext(github, "GitHub") - - Rel(dev, src, "Writes components, pages, styles") - Rel(dev, toolchain, "Triggers via git hooks and pnpm scripts") - Rel(src, config, "Reads aliases and Astro integrations at build time") - Rel(src, build, "astro build compiles to static files") - Rel(build, cdn, "Deployed and served") - Rel(visitor, cdn, "Requests pages and assets") - Rel(toolchain, github, "Enforces commit message convention before push") +# C4 Level 2 — Container + +```mermaid +flowchart TD + DEV["👤 **Developer**\nWrites source code,\nruns pnpm scripts, commits"] + + subgraph REPO["📦 techschool-web — Monorepo boundary"] + direction TD + + CFG["⚙️ **Project Config Layer**\n──────────────\nastro.config.mjs · tsconfig.json · .npmrc\n\nastro.config.mjs → registers Astro 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 (@components, @ui,\n @layouts, @scripts, @styles, @data,\n @contracts, @struct, @images)\n\n.npmrc → pnpm registry & install config"] + + TOOL["🔧 **Dev Toolchain**\n──────────────\nESLint · ls-lint · commitlint\nlint-staged · simple-git-hooks\n\nRuns automatically on every git commit:\n pre-commit → lint-staged (ESLint --fix)\n + ls-lint (file naming)\n commit-msg → commitlint\n (Conventional Commits)\n\nAlso available as pnpm scripts:\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 compiled at build time\nto pure static output"] + + DIST["📄 **Build Output** — /dist\n──────────────\nStatic HTML / CSS / JS\n\nProduced by: astro build\nCompressed by: astro-compressor\nImages optimised by: Sharp\nCSS minified by: LightningCSS\n\nThis folder is what gets deployed —\nno server runtime required"] + 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 +``` diff --git a/src/docs/diagrams/c4level3-components.mmd b/src/docs/diagrams/c4level3-components.mmd index 1aa3536..e487c5d 100644 --- a/src/docs/diagrams/c4level3-components.mmd +++ b/src/docs/diagrams/c4level3-components.mmd @@ -1,32 +1,55 @@ -# C4 Level 3 — Component +# C4 Level 3 — Component (Astro Source) ```mermaid -C4Component - title Component Diagram — Astro Source - - Container_Boundary(src, "src/") { - Component(pages, "src/pages/", "Astro pages (kebab-case)", "File-system routes. Each .astro file becomes an HTML page.") - Component(layouts, "src/layouts/", "Astro layouts (PascalCase)", "Shared page shells — wrap pages with common head, header, footer.") - Component(components, "src/components/", "Astro components (PascalCase)", "Feature components consumed by pages and layouts.") - Component(ui, "src/components/ui/", "UI primitives (PascalCase)", "Reusable low-level Astro components: buttons, cards, etc.") - Component(struct, "src/components/struct/", "Structural components (PascalCase)", "Higher-order layout blocks: sections, grids.") - Component(scripts, "src/scripts/", "Client-side TS (kebab-case)", "Browser JS hydrated by Astro. Uses Embla Carousel.") - Component(styles, "src/styles/", "CSS (kebab-case)", "Global styles. LightningCSS processes them at build time.") - Component(data, "src/data/", "TS data files (kebab-case)", "Static content/config consumed at build time.") - Component(contracts, "src/contracts/", "TS types (kebab-case)", "Shared TypeScript interfaces and type contracts.") - Component(images, "src/images/", "Images (kebab-case)", "Source images processed by Sharp via astro:assets.") - } - - Rel(pages, layouts, "Extends / wraps via slot") - Rel(pages, components, "Imports feature components") - Rel(layouts, components, "Imports structural components") - Rel(components, ui, "Composes UI primitives") - Rel(components, struct, "Uses structural blocks") - Rel(components, scripts, "Client:load / client:idle scripts") - Rel(components, styles, "Imports global and scoped CSS") - Rel(pages, data, "Imports static data at build time") - Rel(components, data, "Reads data for rendering") - Rel(contracts, data, "Types consumed by data files") - Rel(contracts, components, "Types imported for props") - Rel(components, images, "Via astro:assets with Sharp optimisation") +flowchart TD + subgraph SRC["🟦 Astro Source — src/"] + direction TD + + CONTRACTS["📐 **src/contracts/**\n« TypeScript interfaces »\nShared type definitions\nand prop contracts used\nacross the entire codebase"] + + DATA["🗄️ **src/data/**\n« TS data files · kebab-case »\nStatic content consumed\nat build time — no runtime DB.\nExamples: course lists, team info,\npage copy, navigation config"] + + IMAGES["🖼️ **src/images/**\n« kebab-case »\nSource images processed\nby Sharp via astro:assets.\nOutput: WebP / AVIF / resized\nversions in /dist"] + + STYLES["🎨 **src/styles/**\n« CSS · kebab-case »\nGlobal CSS custom properties\nand base styles. Processed by\nLightningCSS at build time\n(autoprefixed + minified)"] + + SCRIPTS["⚡ **src/scripts/**\n« Client-side TS · kebab-case »\nBrowser JavaScript hydrated\nby Astro directives.\nEmbla Carousel for sliders.\nLoaded via client:load\nor client:idle"] + + UI["🧩 **src/components/ui/**\n« PascalCase .astro »\nLow-level design system primitives:\nButton · Card · Badge · Icon wrapper\nReusable with CVA variants\n(class-variance-authority)"] + + STRUCT["🏗️ **src/components/struct/**\n« PascalCase .astro »\nHigher-order structural blocks:\nSection · Grid · Container\nHandle spacing and layout\nwithout business logic"] + + COMPONENTS["🧱 **src/components/**\n« PascalCase .astro »\nFeature-level components:\nHero · Navbar · Footer\nCourseCard · TeamMember\nCompose ui/ and struct/ blocks"] + + LAYOUTS["🖼️ **src/layouts/**\n« PascalCase .astro »\nPage shell templates.\nProvide common head meta,\nOpenGraph, fonts (Onest Variable),\nheader and footer slots"] + + PAGES["📄 **src/pages/**\n« kebab-case .astro »\nFile-system based routes.\nEach file = one URL.\nSpecial _* files (PascalCase)\nfor Astro dynamic segments"] + end + + CONTRACTS -->|"types imported\nfor data shape"| DATA + CONTRACTS -->|"prop types imported\nby components"| COMPONENTS + CONTRACTS -->|"prop types imported\nby layouts"| LAYOUTS + DATA -->|"static content\nread at build"| COMPONENTS + DATA -->|"static content\nread at build"| PAGES + IMAGES -->|"optimised via\nastro:assets"| COMPONENTS + STYLES -->|"global CSS\nimported"| LAYOUTS + SCRIPTS -->|"client:load /\nclient:idle"| COMPONENTS + UI -->|"composed into\nfeature components"| COMPONENTS + STRUCT -->|"layout blocks\nused by"| COMPONENTS + STRUCT -->|"layout blocks\nused by"| LAYOUTS + COMPONENTS -->|"imported into\npage shells"| LAYOUTS + COMPONENTS -->|"imported directly\ninto routes"| PAGES + LAYOUTS -->|"wraps pages\nvia 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 ``` diff --git a/src/docs/diagrams/c4level4-code.mmd b/src/docs/diagrams/c4level4-code.mmd index d97f86c..12fb13d 100644 --- a/src/docs/diagrams/c4level4-code.mmd +++ b/src/docs/diagrams/c4level4-code.mmd @@ -1,34 +1,59 @@ # C4 Level 4 — Code (Config & Toolchain wiring) ```mermaid -C4Component - title Code-level Diagram — Configuration & Toolchain - - Container_Boundary(cfg, "Configuration Files") { - Component(astrocfg, "astro.config.mjs", "Astro config", "Registers integrations: sitemap, compressor, icon, seo-schema. Sets LightningCSS as CSS transformer.") - Component(tscfg, "tsconfig.json", "TypeScript config", "Extends astro/tsconfigs/strict. Defines path aliases: @components, @ui, @layouts, @scripts, @styles, @data, @contracts, @struct, @images.") - Component(npmrc, ".npmrc", "pnpm config", "Sets registry and any pnpm-specific options.") - Component(pkgjson, "package.json", "Project manifest", "Declares scripts (dev, build, preview, lint:fix), git hooks config via simple-git-hooks, and lint-staged file patterns.") - } - - Container_Boundary(tools, "Toolchain Files") { - Component(eslint, "eslint.config.js", "ESLint flat config", "Chains: neostandard, @stylistic, import-x, perfectionist, astro, jsonc, yml, package-json parsers and rules.") - Component(lslint, ".ls-lint.yml", "ls-lint config", "Enforces kebab-case for JS/TS/CSS/media files. Enforces PascalCase for .astro components and layouts. kebab-case for pages.") - Component(commitlint, "commitlint.config.js", "commitlint config", "Extends @commitlint/config-conventional — enforces Conventional Commits on every commit message.") - } - - Container_Boundary(hooks, "Git Hooks (simple-git-hooks)") { - Component(precommit, "pre-commit hook", "shell", "Runs lint-staged (ESLint --fix on staged files) then ls-lint (file naming check).") - Component(commitmsg, "commit-msg hook", "shell", "Runs commitlint to validate commit message format.") - } - - Rel(pkgjson, eslint, "lint:fix script invokes ESLint") - Rel(pkgjson, precommit, "simple-git-hooks registers pre-commit") - Rel(pkgjson, commitmsg, "simple-git-hooks registers commit-msg") - Rel(precommit, eslint, "lint-staged calls ESLint") - Rel(precommit, lslint, "ls-lint validates file names") - Rel(commitmsg, commitlint, "validates message against conventional commits") - Rel(astrocfg, tscfg, "Astro reads tsconfig for path resolution") - Rel(tscfg, eslint, "ESLint uses typescript-eslint parser with tsconfig") - Rel(npmrc, pkgjson, "pnpm reads registry settings before install") +flowchart TD + DEV["👤 **Developer**\ngit commit / git push\npnpm dev / pnpm build"] + + subgraph HOOKS["🪝 Git Hooks — simple-git-hooks"] + direction TB + PRECOMMIT["**pre-commit**\n① pnpm lint-staged\n② pnpm ls-lint"] + COMMITMSG["**commit-msg**\npnpm commitlint -c -e \$1"] + end + + subgraph LINTERS["🔍 Linting Tools"] + direction TB + + ESLINT["📋 **eslint.config.js**\n──────────────\nFlat config chaining:\n· neostandard (base JS/TS rules)\n· @stylistic (formatting)\n· import-x (import ordering)\n· perfectionist (sort imports,\n exports, named imports,\n JSX props — all natural asc)\n· eslint-plugin-astro\n (Astro file support + a11y)\n· astro-eslint-parser\n (parses .astro files)\n· typescript-eslint parser\n (parses TS inside .astro)\n· eslint-plugin-jsonc\n (validates JSON key casing)\n· eslint-plugin-yml\n (YAML indent=3, double quotes)\n· eslint-plugin-package-json\n (validates package.json shape)"] + + LSLINT["📁 **.ls-lint.yml**\n──────────────\nFile naming enforcement:\n· .js .ts .css .json .yml → kebab-case\n· src/components/**/*.astro → PascalCase\n· src/layouts/**/*.astro → PascalCase\n· src/pages/**/*.astro → kebab-case\n· src/pages/_*/*.astro → PascalCase\n· media files → kebab-case\n\nIgnores: dist/ node_modules/\n.git/ config root files"] + + COMMITLINT["💬 **commitlint.config.js**\n──────────────\nextends @commitlint/config-conventional\n\nEnforces format:\n type(scope): description\n\nValid types: feat · fix · docs\n style · refactor · perf\n test · chore · ci · build"] + end + + subgraph CFGFILES["⚙️ Project Configuration"] + direction TB + + PKGJSON["📦 **package.json**\n──────────────\nscripts:\n dev → astro dev\n build → astro build\n preview → astro preview\n lint:fix → eslint --cache --fix\n prepare → simple-git-hooks\n\nlint-staged targets:\n **/*.{js,mjs,cjs,ts} → lint:fix\n src/**/*.astro → lint:fix\n src/**/*.{jsx,tsx} → lint:fix\n\nsimple-git-hooks registration:\n pre-commit · commit-msg\n\nengines:\n node >=22.14.0\n pnpm >=10.5.2"] + + ASTROCFG["🚀 **astro.config.mjs**\n──────────────\nIntegrations registered:\n astro-sitemap → /sitemap.xml\n astro-compressor → gzip + brotli\n astro-icon → SVG icon system\n astro-seo-schema → JSON-LD blocks\n\nvite.css.transformer:\n lightningcss\n (replaces PostCSS,\n faster + modern CSS)"] + + TSCFG["🔷 **tsconfig.json**\n──────────────\nextends astro/tsconfigs/strict\nincludes .astro/types.d.ts\n\nPath aliases (baseUrl = .):\n @components/* → src/components/*\n @ui/* → src/components/ui/*\n @struct/* → src/components/struct/*\n @layouts/* → src/layouts/*\n @scripts/* → src/scripts/*\n @styles/* → src/styles/*\n @data/* → src/data/*\n @contracts → src/contracts\n @images/* → src/images/*"] + + NPMRC["📄 **.npmrc**\n──────────────\npnpm-specific settings:\nregistry config, hoisting rules,\nonlyBuiltDependencies:\n esbuild · sharp\n simple-git-hooks\n unrs-resolver"] + end + + DEV -->|"git commit triggers"| HOOKS + PRECOMMIT -->|"runs ESLint --fix\non staged files"| ESLINT + PRECOMMIT -->|"validates file\nnaming rules"| LSLINT + COMMITMSG -->|"validates commit\nmessage format"| COMMITLINT + DEV -->|"pnpm lint:fix\n(manual run)"| ESLINT + PKGJSON -->|"registers hooks\nvia prepare script"| HOOKS + PKGJSON -->|"lint-staged config\npoints to"| ESLINT + ASTROCFG -->|"reads tsconfig\nfor path resolution\nand TS support"| TSCFG + TSCFG -->|"typescript-eslint\nparser uses tsconfig"| ESLINT + NPMRC -->|"controls pnpm install\nbefore package.json 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 ``` From 6dc9d7381de3620c76e02a30c66c4c6cadd9c421 Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:32:20 -0300 Subject: [PATCH 3/9] more bug fix --- src/docs/diagrams/c4level1-system-context.mmd | 3 +-- src/docs/diagrams/c4level2-containers.mmd | 3 +-- src/docs/diagrams/c4level3-components.mmd | 3 +-- src/docs/diagrams/c4level4-code.mmd | 3 +-- 4 files changed, 4 insertions(+), 8 deletions(-) diff --git a/src/docs/diagrams/c4level1-system-context.mmd b/src/docs/diagrams/c4level1-system-context.mmd index 69e4895..a97e558 100644 --- a/src/docs/diagrams/c4level1-system-context.mmd +++ b/src/docs/diagrams/c4level1-system-context.mmd @@ -1,5 +1,4 @@ -# C4 Level 1 — System Context - +# C4 Level 1 — System Context --- IGNORE --- ```mermaid flowchart TD DEV["👤 **Developer**\n──────────────\nTeam member at UXCorpRangel\nWrites code, reviews PRs,\nmanages releases"] diff --git a/src/docs/diagrams/c4level2-containers.mmd b/src/docs/diagrams/c4level2-containers.mmd index 96bfc22..64bb582 100644 --- a/src/docs/diagrams/c4level2-containers.mmd +++ b/src/docs/diagrams/c4level2-containers.mmd @@ -1,5 +1,4 @@ -# C4 Level 2 — Container - +# C4 Level 2 — Container (Monorepo) --- IGNORE --- ```mermaid flowchart TD DEV["👤 **Developer**\nWrites source code,\nruns pnpm scripts, commits"] diff --git a/src/docs/diagrams/c4level3-components.mmd b/src/docs/diagrams/c4level3-components.mmd index e487c5d..1b17f81 100644 --- a/src/docs/diagrams/c4level3-components.mmd +++ b/src/docs/diagrams/c4level3-components.mmd @@ -1,5 +1,4 @@ -# C4 Level 3 — Component (Astro Source) - +# C4 Level 3 — Component (Astro Source) --- IGNORE --- ```mermaid flowchart TD subgraph SRC["🟦 Astro Source — src/"] diff --git a/src/docs/diagrams/c4level4-code.mmd b/src/docs/diagrams/c4level4-code.mmd index 12fb13d..e05d873 100644 --- a/src/docs/diagrams/c4level4-code.mmd +++ b/src/docs/diagrams/c4level4-code.mmd @@ -1,5 +1,4 @@ -# C4 Level 4 — Code (Config & Toolchain wiring) - +# C4 Level 4 — Code (Project Configuration & Tooling) --- IGNORE --- ```mermaid flowchart TD DEV["👤 **Developer**\ngit commit / git push\npnpm dev / pnpm build"] From 511dab71efb8a3e98e29a875fd884492ba24347d Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:32:47 -0300 Subject: [PATCH 4/9] again diagram mermaid fix --- src/docs/diagrams/c4level1-system-context.mmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/diagrams/c4level1-system-context.mmd b/src/docs/diagrams/c4level1-system-context.mmd index a97e558..517b5a6 100644 --- a/src/docs/diagrams/c4level1-system-context.mmd +++ b/src/docs/diagrams/c4level1-system-context.mmd @@ -1,4 +1,4 @@ -# C4 Level 1 — System Context --- IGNORE --- + ```mermaid flowchart TD DEV["👤 **Developer**\n──────────────\nTeam member at UXCorpRangel\nWrites code, reviews PRs,\nmanages releases"] From 50671770c873e468991a6976e0ac4a3ddeb044be Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:33:49 -0300 Subject: [PATCH 5/9] i hate mermaid diagrams --- src/docs/diagrams/c4level1-system-context.mmd | 1 - 1 file changed, 1 deletion(-) diff --git a/src/docs/diagrams/c4level1-system-context.mmd b/src/docs/diagrams/c4level1-system-context.mmd index 517b5a6..13cab79 100644 --- a/src/docs/diagrams/c4level1-system-context.mmd +++ b/src/docs/diagrams/c4level1-system-context.mmd @@ -1,4 +1,3 @@ - ```mermaid flowchart TD DEV["👤 **Developer**\n──────────────\nTeam member at UXCorpRangel\nWrites code, reviews PRs,\nmanages releases"] From 6502bd39181235badec86c0f86752120f2fa8677 Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:34:50 -0300 Subject: [PATCH 6/9] replace mermaid from mmd to md --- .../{c4level1-system-context.mmd => c4level1-system-context.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename src/docs/diagrams/{c4level1-system-context.mmd => c4level1-system-context.md} (100%) diff --git a/src/docs/diagrams/c4level1-system-context.mmd b/src/docs/diagrams/c4level1-system-context.md similarity index 100% rename from src/docs/diagrams/c4level1-system-context.mmd rename to src/docs/diagrams/c4level1-system-context.md From 66babe5532da9d2759d1c673e67f5930a615a838 Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:37:28 -0300 Subject: [PATCH 7/9] final diagrams with teachable README --- src/docs/README.md | 36 +++++++++++++++++++ ...-containers.mmd => c4level2-containers.md} | 9 +++-- ...-components.mmd => c4level3-components.md} | 25 +++++++------ .../{c4level4-code.mmd => c4level4-code.md} | 21 ++++++----- 4 files changed, 62 insertions(+), 29 deletions(-) create mode 100644 src/docs/README.md rename src/docs/diagrams/{c4level2-containers.mmd => c4level2-containers.md} (62%) rename src/docs/diagrams/{c4level3-components.mmd => c4level3-components.md} (64%) rename src/docs/diagrams/{c4level4-code.mmd => c4level4-code.md} (59%) diff --git a/src/docs/README.md b/src/docs/README.md new file mode 100644 index 0000000..0666da2 --- /dev/null +++ b/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. diff --git a/src/docs/diagrams/c4level2-containers.mmd b/src/docs/diagrams/c4level2-containers.md similarity index 62% rename from src/docs/diagrams/c4level2-containers.mmd rename to src/docs/diagrams/c4level2-containers.md index 64bb582..279a24c 100644 --- a/src/docs/diagrams/c4level2-containers.mmd +++ b/src/docs/diagrams/c4level2-containers.md @@ -1,4 +1,3 @@ -# C4 Level 2 — Container (Monorepo) --- IGNORE --- ```mermaid flowchart TD DEV["👤 **Developer**\nWrites source code,\nruns pnpm scripts, commits"] @@ -6,13 +5,13 @@ flowchart TD subgraph REPO["📦 techschool-web — Monorepo boundary"] direction TD - CFG["⚙️ **Project Config Layer**\n──────────────\nastro.config.mjs · tsconfig.json · .npmrc\n\nastro.config.mjs → registers Astro 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 (@components, @ui,\n @layouts, @scripts, @styles, @data,\n @contracts, @struct, @images)\n\n.npmrc → pnpm registry & install config"] + 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\nRuns automatically on every git commit:\n pre-commit → lint-staged (ESLint --fix)\n + ls-lint (file naming)\n commit-msg → commitlint\n (Conventional Commits)\n\nAlso available as pnpm scripts:\n pnpm lint:fix · pnpm prepare"] + 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 compiled at build time\nto pure static output"] + 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\nProduced by: astro build\nCompressed by: astro-compressor\nImages optimised by: Sharp\nCSS minified by: LightningCSS\n\nThis folder is what gets deployed —\nno server runtime required"] + 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"] diff --git a/src/docs/diagrams/c4level3-components.mmd b/src/docs/diagrams/c4level3-components.md similarity index 64% rename from src/docs/diagrams/c4level3-components.mmd rename to src/docs/diagrams/c4level3-components.md index 1b17f81..552df54 100644 --- a/src/docs/diagrams/c4level3-components.mmd +++ b/src/docs/diagrams/c4level3-components.md @@ -1,4 +1,3 @@ -# C4 Level 3 — Component (Astro Source) --- IGNORE --- ```mermaid flowchart TD subgraph SRC["🟦 Astro Source — src/"] @@ -6,33 +5,33 @@ flowchart TD CONTRACTS["📐 **src/contracts/**\n« TypeScript interfaces »\nShared type definitions\nand prop contracts used\nacross the entire codebase"] - DATA["🗄️ **src/data/**\n« TS data files · kebab-case »\nStatic content consumed\nat build time — no runtime DB.\nExamples: course lists, team info,\npage copy, navigation config"] + DATA["🗄️ **src/data/**\n« TS data files · kebab-case »\nStatic content consumed at build time\nNo runtime DB needed\nExamples: course lists, team info,\npage copy, navigation config"] - IMAGES["🖼️ **src/images/**\n« kebab-case »\nSource images processed\nby Sharp via astro:assets.\nOutput: WebP / AVIF / resized\nversions in /dist"] + IMAGES["🖼️ **src/images/**\n« kebab-case »\nSource images processed by Sharp\nvia astro:assets\nOutput: WebP / AVIF / resized\nversions placed in /dist"] - STYLES["🎨 **src/styles/**\n« CSS · kebab-case »\nGlobal CSS custom properties\nand base styles. Processed by\nLightningCSS at build time\n(autoprefixed + minified)"] + STYLES["🎨 **src/styles/**\n« CSS · kebab-case »\nGlobal CSS custom properties\nand base styles\nProcessed by LightningCSS\nat build time — autoprefixed + minified"] - SCRIPTS["⚡ **src/scripts/**\n« Client-side TS · kebab-case »\nBrowser JavaScript hydrated\nby Astro directives.\nEmbla Carousel for sliders.\nLoaded via client:load\nor client:idle"] + SCRIPTS["⚡ **src/scripts/**\n« Client-side TS · kebab-case »\nBrowser JavaScript hydrated\nby Astro client directives\nEmbla Carousel for sliders\nLoaded via client:load or client:idle"] - UI["🧩 **src/components/ui/**\n« PascalCase .astro »\nLow-level design system primitives:\nButton · Card · Badge · Icon wrapper\nReusable with CVA variants\n(class-variance-authority)"] + UI["🧩 **src/components/ui/**\n« PascalCase .astro »\nLow-level design system primitives:\nButton · Card · Badge · Icon wrapper\nVariants managed with CVA\n(class-variance-authority)"] STRUCT["🏗️ **src/components/struct/**\n« PascalCase .astro »\nHigher-order structural blocks:\nSection · Grid · Container\nHandle spacing and layout\nwithout business logic"] - COMPONENTS["🧱 **src/components/**\n« PascalCase .astro »\nFeature-level components:\nHero · Navbar · Footer\nCourseCard · TeamMember\nCompose ui/ and struct/ blocks"] + COMPONENTS["🧱 **src/components/**\n« PascalCase .astro »\nFeature-level components:\nHero · Navbar · Footer · CourseCard\nCompose ui/ primitives\nand struct/ layout blocks"] - LAYOUTS["🖼️ **src/layouts/**\n« PascalCase .astro »\nPage shell templates.\nProvide common head meta,\nOpenGraph, fonts (Onest Variable),\nheader and footer slots"] + LAYOUTS["🖼️ **src/layouts/**\n« PascalCase .astro »\nPage shell templates\nCommon head meta · OpenGraph\nFonts: Onest Variable\nHeader and footer via slots"] - PAGES["📄 **src/pages/**\n« kebab-case .astro »\nFile-system based routes.\nEach file = one URL.\nSpecial _* files (PascalCase)\nfor Astro dynamic segments"] + PAGES["📄 **src/pages/**\n« kebab-case .astro »\nFile-system based routes\nEach file = one URL\n_* files use PascalCase\nfor Astro dynamic segments"] end - CONTRACTS -->|"types imported\nfor data shape"| DATA - CONTRACTS -->|"prop types imported\nby components"| COMPONENTS - CONTRACTS -->|"prop types imported\nby layouts"| LAYOUTS + CONTRACTS -->|"types shape\ndata files"| DATA + CONTRACTS -->|"prop types used\nby components"| COMPONENTS + CONTRACTS -->|"prop types used\nby layouts"| LAYOUTS DATA -->|"static content\nread at build"| COMPONENTS DATA -->|"static content\nread at build"| PAGES IMAGES -->|"optimised via\nastro:assets"| COMPONENTS STYLES -->|"global CSS\nimported"| LAYOUTS - SCRIPTS -->|"client:load /\nclient:idle"| COMPONENTS + SCRIPTS -->|"hydrated via\nclient directives"| COMPONENTS UI -->|"composed into\nfeature components"| COMPONENTS STRUCT -->|"layout blocks\nused by"| COMPONENTS STRUCT -->|"layout blocks\nused by"| LAYOUTS diff --git a/src/docs/diagrams/c4level4-code.mmd b/src/docs/diagrams/c4level4-code.md similarity index 59% rename from src/docs/diagrams/c4level4-code.mmd rename to src/docs/diagrams/c4level4-code.md index e05d873..c284bfc 100644 --- a/src/docs/diagrams/c4level4-code.mmd +++ b/src/docs/diagrams/c4level4-code.md @@ -1,4 +1,3 @@ -# C4 Level 4 — Code (Project Configuration & Tooling) --- IGNORE --- ```mermaid flowchart TD DEV["👤 **Developer**\ngit commit / git push\npnpm dev / pnpm build"] @@ -12,35 +11,35 @@ flowchart TD subgraph LINTERS["🔍 Linting Tools"] direction TB - ESLINT["📋 **eslint.config.js**\n──────────────\nFlat config chaining:\n· neostandard (base JS/TS rules)\n· @stylistic (formatting)\n· import-x (import ordering)\n· perfectionist (sort imports,\n exports, named imports,\n JSX props — all natural asc)\n· eslint-plugin-astro\n (Astro file support + a11y)\n· astro-eslint-parser\n (parses .astro files)\n· typescript-eslint parser\n (parses TS inside .astro)\n· eslint-plugin-jsonc\n (validates JSON key casing)\n· eslint-plugin-yml\n (YAML indent=3, double quotes)\n· eslint-plugin-package-json\n (validates package.json shape)"] + ESLINT["📋 **eslint.config.js**\n──────────────\nFlat config chaining:\n· neostandard — base JS/TS rules\n· @stylistic — formatting rules\n· import-x — import ordering\n· perfectionist — sort imports,\n exports, named imports, JSX props\n all natural ascending order\n· eslint-plugin-astro\n Astro file support + a11y\n· astro-eslint-parser\n parses .astro files\n· typescript-eslint parser\n parses TS inside .astro\n· eslint-plugin-jsonc\n validates JSON key casing\n· eslint-plugin-yml\n YAML indent=3, double quotes\n· eslint-plugin-package-json\n validates package.json shape"] - LSLINT["📁 **.ls-lint.yml**\n──────────────\nFile naming enforcement:\n· .js .ts .css .json .yml → kebab-case\n· src/components/**/*.astro → PascalCase\n· src/layouts/**/*.astro → PascalCase\n· src/pages/**/*.astro → kebab-case\n· src/pages/_*/*.astro → PascalCase\n· media files → kebab-case\n\nIgnores: dist/ node_modules/\n.git/ config root files"] + LSLINT["📁 **.ls-lint.yml**\n──────────────\nFile naming enforcement:\n· .js .ts .css .json .yml → kebab-case\n· src/components/**/*.astro → PascalCase\n· src/layouts/**/*.astro → PascalCase\n· src/pages/**/*.astro → kebab-case\n· src/pages/_*/*.astro → PascalCase\n· media and image files → kebab-case\n\nIgnores: dist/ node_modules/ .git/\nand root-level config files"] - COMMITLINT["💬 **commitlint.config.js**\n──────────────\nextends @commitlint/config-conventional\n\nEnforces format:\n type(scope): description\n\nValid types: feat · fix · docs\n style · refactor · perf\n test · chore · ci · build"] + COMMITLINT["💬 **commitlint.config.js**\n──────────────\nextends @commitlint/config-conventional\n\nEnforces format:\n type(scope): description\n\nValid types:\n feat · fix · docs · style\n refactor · perf · test\n chore · ci · build"] end subgraph CFGFILES["⚙️ Project Configuration"] direction TB - PKGJSON["📦 **package.json**\n──────────────\nscripts:\n dev → astro dev\n build → astro build\n preview → astro preview\n lint:fix → eslint --cache --fix\n prepare → simple-git-hooks\n\nlint-staged targets:\n **/*.{js,mjs,cjs,ts} → lint:fix\n src/**/*.astro → lint:fix\n src/**/*.{jsx,tsx} → lint:fix\n\nsimple-git-hooks registration:\n pre-commit · commit-msg\n\nengines:\n node >=22.14.0\n pnpm >=10.5.2"] + PKGJSON["📦 **package.json**\n──────────────\nscripts:\n dev → astro dev\n build → astro build\n preview → astro preview\n lint:fix → eslint --cache --fix\n prepare → simple-git-hooks\n\nlint-staged targets:\n **/*.{js,mjs,cjs,ts} → lint:fix\n src/**/*.astro → lint:fix\n src/**/*.{jsx,tsx} → lint:fix\n\nengines:\n node >=22.14.0\n pnpm >=10.5.2"] - ASTROCFG["🚀 **astro.config.mjs**\n──────────────\nIntegrations registered:\n astro-sitemap → /sitemap.xml\n astro-compressor → gzip + brotli\n astro-icon → SVG icon system\n astro-seo-schema → JSON-LD blocks\n\nvite.css.transformer:\n lightningcss\n (replaces PostCSS,\n faster + modern CSS)"] + ASTROCFG["🚀 **astro.config.mjs**\n──────────────\nIntegrations:\n astro-sitemap → /sitemap.xml\n astro-compressor → gzip + brotli\n astro-icon → SVG icon system\n astro-seo-schema → JSON-LD blocks\n\nvite.css.transformer:\n lightningcss\n replaces PostCSS,\n faster with modern CSS support"] TSCFG["🔷 **tsconfig.json**\n──────────────\nextends astro/tsconfigs/strict\nincludes .astro/types.d.ts\n\nPath aliases (baseUrl = .):\n @components/* → src/components/*\n @ui/* → src/components/ui/*\n @struct/* → src/components/struct/*\n @layouts/* → src/layouts/*\n @scripts/* → src/scripts/*\n @styles/* → src/styles/*\n @data/* → src/data/*\n @contracts → src/contracts\n @images/* → src/images/*"] - NPMRC["📄 **.npmrc**\n──────────────\npnpm-specific settings:\nregistry config, hoisting rules,\nonlyBuiltDependencies:\n esbuild · sharp\n simple-git-hooks\n unrs-resolver"] + NPMRC["📄 **.npmrc**\n──────────────\npnpm-specific settings\nregistry config and hoisting rules\nonlyBuiltDependencies:\n esbuild · sharp\n simple-git-hooks · unrs-resolver"] end DEV -->|"git commit triggers"| HOOKS PRECOMMIT -->|"runs ESLint --fix\non staged files"| ESLINT PRECOMMIT -->|"validates file\nnaming rules"| LSLINT COMMITMSG -->|"validates commit\nmessage format"| COMMITLINT - DEV -->|"pnpm lint:fix\n(manual run)"| ESLINT + DEV -->|"pnpm lint:fix\nmanual run"| ESLINT PKGJSON -->|"registers hooks\nvia prepare script"| HOOKS - PKGJSON -->|"lint-staged config\npoints to"| ESLINT - ASTROCFG -->|"reads tsconfig\nfor path resolution\nand TS support"| TSCFG + PKGJSON -->|"lint-staged config\npoints to ESLint"| ESLINT + ASTROCFG -->|"reads tsconfig for\npath resolution"| TSCFG TSCFG -->|"typescript-eslint\nparser uses tsconfig"| ESLINT - NPMRC -->|"controls pnpm install\nbefore package.json deps"| PKGJSON + NPMRC -->|"controls pnpm install\nbefore deps resolve"| PKGJSON style DEV fill:#1168BD,color:#fff,stroke:#0e56a0 style PRECOMMIT fill:#6A1B9A,color:#fff,stroke:#4a148c From b99f9e29d63169f752c869f2e0a6b5eecbdc9a51 Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:40:15 -0300 Subject: [PATCH 8/9] visualization fix --- src/docs/diagrams/c4level2-containers.md | 2 - src/docs/diagrams/c4level3-components.md | 2 - src/docs/diagrams/c4level4-code.md | 56 ++++++++++-------------- 3 files changed, 23 insertions(+), 37 deletions(-) diff --git a/src/docs/diagrams/c4level2-containers.md b/src/docs/diagrams/c4level2-containers.md index 279a24c..d5d6d58 100644 --- a/src/docs/diagrams/c4level2-containers.md +++ b/src/docs/diagrams/c4level2-containers.md @@ -3,8 +3,6 @@ flowchart TD DEV["👤 **Developer**\nWrites source code,\nruns pnpm scripts, commits"] subgraph REPO["📦 techschool-web — Monorepo boundary"] - direction TD - 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"] diff --git a/src/docs/diagrams/c4level3-components.md b/src/docs/diagrams/c4level3-components.md index 552df54..1564afa 100644 --- a/src/docs/diagrams/c4level3-components.md +++ b/src/docs/diagrams/c4level3-components.md @@ -1,8 +1,6 @@ ```mermaid flowchart TD subgraph SRC["🟦 Astro Source — src/"] - direction TD - CONTRACTS["📐 **src/contracts/**\n« TypeScript interfaces »\nShared type definitions\nand prop contracts used\nacross the entire codebase"] DATA["🗄️ **src/data/**\n« TS data files · kebab-case »\nStatic content consumed at build time\nNo runtime DB needed\nExamples: course lists, team info,\npage copy, navigation config"] diff --git a/src/docs/diagrams/c4level4-code.md b/src/docs/diagrams/c4level4-code.md index c284bfc..83770af 100644 --- a/src/docs/diagrams/c4level4-code.md +++ b/src/docs/diagrams/c4level4-code.md @@ -1,45 +1,35 @@ ```mermaid flowchart TD - DEV["👤 **Developer**\ngit commit / git push\npnpm dev / pnpm build"] + DEV["👤 Developer\ngit commit / pnpm dev / pnpm build"] - subgraph HOOKS["🪝 Git Hooks — simple-git-hooks"] - direction TB - PRECOMMIT["**pre-commit**\n① pnpm lint-staged\n② pnpm ls-lint"] - COMMITMSG["**commit-msg**\npnpm commitlint -c -e \$1"] + subgraph HOOKS["Git Hooks — simple-git-hooks"] + PRECOMMIT["pre-commit\nlint-staged + ls-lint"] + COMMITMSG["commit-msg\ncommitlint"] end - subgraph LINTERS["🔍 Linting Tools"] - direction TB - - ESLINT["📋 **eslint.config.js**\n──────────────\nFlat config chaining:\n· neostandard — base JS/TS rules\n· @stylistic — formatting rules\n· import-x — import ordering\n· perfectionist — sort imports,\n exports, named imports, JSX props\n all natural ascending order\n· eslint-plugin-astro\n Astro file support + a11y\n· astro-eslint-parser\n parses .astro files\n· typescript-eslint parser\n parses TS inside .astro\n· eslint-plugin-jsonc\n validates JSON key casing\n· eslint-plugin-yml\n YAML indent=3, double quotes\n· eslint-plugin-package-json\n validates package.json shape"] - - LSLINT["📁 **.ls-lint.yml**\n──────────────\nFile naming enforcement:\n· .js .ts .css .json .yml → kebab-case\n· src/components/**/*.astro → PascalCase\n· src/layouts/**/*.astro → PascalCase\n· src/pages/**/*.astro → kebab-case\n· src/pages/_*/*.astro → PascalCase\n· media and image files → kebab-case\n\nIgnores: dist/ node_modules/ .git/\nand root-level config files"] - - COMMITLINT["💬 **commitlint.config.js**\n──────────────\nextends @commitlint/config-conventional\n\nEnforces format:\n type(scope): description\n\nValid types:\n feat · fix · docs · style\n refactor · perf · test\n chore · ci · build"] + 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"] - direction TB - - PKGJSON["📦 **package.json**\n──────────────\nscripts:\n dev → astro dev\n build → astro build\n preview → astro preview\n lint:fix → eslint --cache --fix\n prepare → simple-git-hooks\n\nlint-staged targets:\n **/*.{js,mjs,cjs,ts} → lint:fix\n src/**/*.astro → lint:fix\n src/**/*.{jsx,tsx} → lint:fix\n\nengines:\n node >=22.14.0\n pnpm >=10.5.2"] - - ASTROCFG["🚀 **astro.config.mjs**\n──────────────\nIntegrations:\n astro-sitemap → /sitemap.xml\n astro-compressor → gzip + brotli\n astro-icon → SVG icon system\n astro-seo-schema → JSON-LD blocks\n\nvite.css.transformer:\n lightningcss\n replaces PostCSS,\n faster with modern CSS support"] - - TSCFG["🔷 **tsconfig.json**\n──────────────\nextends astro/tsconfigs/strict\nincludes .astro/types.d.ts\n\nPath aliases (baseUrl = .):\n @components/* → src/components/*\n @ui/* → src/components/ui/*\n @struct/* → src/components/struct/*\n @layouts/* → src/layouts/*\n @scripts/* → src/scripts/*\n @styles/* → src/styles/*\n @data/* → src/data/*\n @contracts → src/contracts\n @images/* → src/images/*"] - - NPMRC["📄 **.npmrc**\n──────────────\npnpm-specific settings\nregistry config and hoisting rules\nonlyBuiltDependencies:\n esbuild · sharp\n simple-git-hooks · unrs-resolver"] + 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 triggers"| HOOKS - PRECOMMIT -->|"runs ESLint --fix\non staged files"| ESLINT - PRECOMMIT -->|"validates file\nnaming rules"| LSLINT - COMMITMSG -->|"validates commit\nmessage format"| COMMITLINT - DEV -->|"pnpm lint:fix\nmanual run"| ESLINT - PKGJSON -->|"registers hooks\nvia prepare script"| HOOKS - PKGJSON -->|"lint-staged config\npoints to ESLint"| ESLINT - ASTROCFG -->|"reads tsconfig for\npath resolution"| TSCFG - TSCFG -->|"typescript-eslint\nparser uses tsconfig"| ESLINT - NPMRC -->|"controls pnpm install\nbefore deps resolve"| PKGJSON + 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 From 358618caeafdff0fb347d0759932f018fc426599 Mon Sep 17 00:00:00 2001 From: Felipe Carvajal Date: Tue, 17 Feb 2026 15:41:59 -0300 Subject: [PATCH 9/9] data summary fix --- src/docs/diagrams/c4level3-components.md | 59 ++++++++++-------------- 1 file changed, 25 insertions(+), 34 deletions(-) diff --git a/src/docs/diagrams/c4level3-components.md b/src/docs/diagrams/c4level3-components.md index 1564afa..8c7ced4 100644 --- a/src/docs/diagrams/c4level3-components.md +++ b/src/docs/diagrams/c4level3-components.md @@ -1,41 +1,32 @@ ```mermaid flowchart TD - subgraph SRC["🟦 Astro Source — src/"] - CONTRACTS["📐 **src/contracts/**\n« TypeScript interfaces »\nShared type definitions\nand prop contracts used\nacross the entire codebase"] - - DATA["🗄️ **src/data/**\n« TS data files · kebab-case »\nStatic content consumed at build time\nNo runtime DB needed\nExamples: course lists, team info,\npage copy, navigation config"] - - IMAGES["🖼️ **src/images/**\n« kebab-case »\nSource images processed by Sharp\nvia astro:assets\nOutput: WebP / AVIF / resized\nversions placed in /dist"] - - STYLES["🎨 **src/styles/**\n« CSS · kebab-case »\nGlobal CSS custom properties\nand base styles\nProcessed by LightningCSS\nat build time — autoprefixed + minified"] - - SCRIPTS["⚡ **src/scripts/**\n« Client-side TS · kebab-case »\nBrowser JavaScript hydrated\nby Astro client directives\nEmbla Carousel for sliders\nLoaded via client:load or client:idle"] - - UI["🧩 **src/components/ui/**\n« PascalCase .astro »\nLow-level design system primitives:\nButton · Card · Badge · Icon wrapper\nVariants managed with CVA\n(class-variance-authority)"] - - STRUCT["🏗️ **src/components/struct/**\n« PascalCase .astro »\nHigher-order structural blocks:\nSection · Grid · Container\nHandle spacing and layout\nwithout business logic"] - - COMPONENTS["🧱 **src/components/**\n« PascalCase .astro »\nFeature-level components:\nHero · Navbar · Footer · CourseCard\nCompose ui/ primitives\nand struct/ layout blocks"] - - LAYOUTS["🖼️ **src/layouts/**\n« PascalCase .astro »\nPage shell templates\nCommon head meta · OpenGraph\nFonts: Onest Variable\nHeader and footer via slots"] - - PAGES["📄 **src/pages/**\n« kebab-case .astro »\nFile-system based routes\nEach file = one URL\n_* files use PascalCase\nfor Astro dynamic segments"] + 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 shape\ndata files"| DATA - CONTRACTS -->|"prop types used\nby components"| COMPONENTS - CONTRACTS -->|"prop types used\nby layouts"| LAYOUTS - DATA -->|"static content\nread at build"| COMPONENTS - DATA -->|"static content\nread at build"| PAGES - IMAGES -->|"optimised via\nastro:assets"| COMPONENTS - STYLES -->|"global CSS\nimported"| LAYOUTS - SCRIPTS -->|"hydrated via\nclient directives"| COMPONENTS - UI -->|"composed into\nfeature components"| COMPONENTS - STRUCT -->|"layout blocks\nused by"| COMPONENTS - STRUCT -->|"layout blocks\nused by"| LAYOUTS - COMPONENTS -->|"imported into\npage shells"| LAYOUTS - COMPONENTS -->|"imported directly\ninto routes"| PAGES - LAYOUTS -->|"wraps pages\nvia slot"| PAGES + 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