How nguyenphuc22/design-patterns works
Dự án là gì (type + purpose)
Đây không phải là một “running system” kiểu web-app/backend service. Nó là một repository sách/tài liệu về Design Patterns (tiếng Việt), kèm:
• Nội dung sách dưới dạng Markdown (Writerside + docs/Book).
• Code mẫu (Java + Kotlin) minh hoạ các pattern (trong src/...).
• Build tooling (Gradle wrapper, build.gradle, settings.gradle) để build/pack tài liệu hoặc chạy demo (tuỳ cấu hình).
• CI/CD qua GitHub Actions (.github/workflows/deploy.yml) để build và deploy tài liệu (nhiều khả năng lên GitHub Pages hoặc một static hosting tương tự).
Authoring / Content layer
• Writerside/
• topics/*.md: nội dung chính (Intro, Creational/Structural/Behavioral, từng pattern).
• writerside.cfg, cfg/*, buildprofiles.xml: cấu hình build Writerside.
• images/: assets cho Writerside.
• docs/Book/*.md: bản “book format” (chương 1..6).
• SUMMARY.md: mục lục/điều hướng nội dung.
• docs/images/**: ảnh đã export/đính kèm theo từng pattern.
Code samples layer (minh hoạ pattern)
• src/main/java/design/patterns/creational/singleton/*: Java Singleton examples (+ README riêng).
• src/structural patterns/**: Kotlin examples (Composite/Decorator/Proxy…).
• src/Behavioral Patterns/**: Kotlin examples (Command…).
Build / Tooling / CI-CD
• build.gradle, settings.gradle, gradle/wrapper/*, gradlew*: build system (Gradle).
• .github/workflows/deploy.yml: pipeline deploy.
• local.properties: cấu hình local (không nên phụ thuộc runtime, nhưng có thể phục vụ build).
Project meta/community
• CONTRIBUTING.md, LICENSE.md, .github/FUNDING.yml: contribution & funding.
• README mô tả mục tiêu, ngôn ngữ hỗ trợ, cách đóng góp, liên kết issue.
(Tuỳ chọn) Content/Code Component Map (nội dung & code mẫu được tổ chức ra sao)
Bạn có thể dùng C4 Model làm khung, nhưng điều chỉnh cho phù hợp “documentation system”.
CI/CD: GitHub Actions
• workflow deploy.yml
Doc Builder
• Writerside build (input: topics/cfg/images; output: static site)
• (nếu Gradle orchestrate build) Gradle task runner
Static Site Hosting
• GitHub Pages / static hosting
End Users (Browser)
• consume static HTML/CSS/JS/assets
Quan hệ
• Repo → CI (trigger on push/merge)
• CI → Doc Builder (build)
• Builder → Hosting (publish artifacts)
• Browser ↔ Hosting (serve static)
Author edits
• Writerside/topics/*.md
• docs/Book/*.md
• code samples trong src/...
Commit/PR
• GitHub PR review (optional gate)
CI Build
• Checkout code
• Setup JDK/Gradle
• Run Writerside build (hoặc Gradle tasks)
• Generate static site artifacts
Deploy
• Upload artifacts → GitHub Pages (hoặc target khác)
Consume
• Reader loads pages
• (Optional) analytics events → GA
4d) Component Map View (nội dung & code mẫu)
Ở view này, mục tiêu là “repo được tổ chức ra sao”, không phải runtime.
Nên nhóm thành 4 cụm:
• Writerside content: Writerside/topics + Writerside/cfg + Writerside/images
• Book content: docs/Book + SUMMARY.md
• Code examples:
• Java examples: src/main/java/design/patterns/...
• Kotlin examples: src/structural patterns/**, src/Behavioral Patterns/**
• Gắn tag “educational samples (non-production)”
Vẽ mũi tên:
• *.drawio → docs/images/... (exported images)
• Code examples ↔ referenced by docs (nếu docs có link tới code; nếu chưa rõ, dùng đường nét đứt “referenced in content”)
Quy tắc vẽ quan hệ / tương tác (để chính xác)
• “build static HTML”
• “publish artifact”
• “serve HTTP”
• Gắn “source of truth” vào component
• “Topics (Markdown) = source”
• “Images = generated/exported artifacts”
• Writerside (documentation engine)
• Gradle + Gradle Wrapper (build.gradle, gradlew)
• GitHub Actions (deploy.yml)
• Java/Kotlin (code samples)
• Static hosting (GitHub Pages) (suy đoán hợp lý từ workflow deploy; hãy xác nhận bằng deploy.yml)
• Màu xanh: Content sources (Markdown)
• Màu tím: Build/CI (Gradle, GitHub Actions)
• Màu cam: Artifacts/output (static site, exported images)
• Màu xám: External systems (GitHub, Hosting, GA, Payment)
• Cloud: Hosting/External
“Don’t overthink” nhưng tách tối đa component (đúng tinh thần yêu cầu)
• Writerside topics/config/images
• docs/Book + SUMMARY
• code samples (Java/Kotlin)
• CI workflow → tách thành:
• Trigger
• Build steps
• Artifact output
• Deploy step
• Hosting → tách:
• Static pages
• Static assets (images)
• (Optional) analytics script include