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/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/c4level1-system-context.md b/src/docs/diagrams/c4level1-system-context.md new file mode 100644 index 0000000..13cab79 --- /dev/null +++ b/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 +``` diff --git a/src/docs/diagrams/c4level2-containers.md b/src/docs/diagrams/c4level2-containers.md new file mode 100644 index 0000000..d5d6d58 --- /dev/null +++ b/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 +``` diff --git a/src/docs/diagrams/c4level3-components.md b/src/docs/diagrams/c4level3-components.md new file mode 100644 index 0000000..8c7ced4 --- /dev/null +++ b/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 +``` diff --git a/src/docs/diagrams/c4level4-code.md b/src/docs/diagrams/c4level4-code.md new file mode 100644 index 0000000..83770af --- /dev/null +++ b/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 +```