How suphanf/solutions-architect-principles works
Project type and purpose
• This is a static documentation/book repository (“Solutions Architect Principles”) organized as a set of Markdown-based chapters.
• Its purpose is to produce a navigable, styled website (or PDF/e-book) from these Markdown files so readers can learn architecture principles.
File structure
• Top-level files:
• README.md – high-level overview and table of contents
• Top-level directories:
• 01-Role-and-Responsibilities
• 03-Performance-and-Scalability
• 04-Availability-and-Reliability
• 05-Security
• 06-Cost-Optimization
• Each chapter folder contains its own README.md with the chapter content.
• No source code folders or tests—indicates a static site/content generator workflow.
README for additional insights
• Describes chapters but makes no explicit mention of which static site generator (SSG) is used.
• Implied workflow: authors update Markdown → SSG builds site → site is deployed.
Main components
a. Content layer
– Raw Markdown files (project’s chapter directories & root README)
b. Build layer
– Static Site Generator (e.g., MkDocs, Hugo, Jekyll, GitBook CLI)
– Configuration files (e.g., mkdocs.yml, config.toml)
– Themes & plugins (syntax highlighting, navigation)
c. CI/CD layer
– Version control system (GitHub/GitLab)
– CI pipeline (GitHub Actions, GitLab CI, CircleCI) that:
• Lints Markdown
• Runs link checks
• Invokes SSG to build HTML/CSS/JS assets
d. Hosting & Delivery layer
– Static hosting (GitHub Pages, Netlify, Vercel, S3+CloudFront)
– CDN for global distribution
e. Consumption layer
– End users’ browsers requesting pages via HTTPS
Relationships & interactions
1. Author commits Markdown → Git repo
2. CI/CD pipeline triggers on push → builds site using SSG
3. Artifacts (static HTML/CSS/JS) are published to hosting
4. CDN caches assets and delivers to readers
Architectural patterns & design principles
• Content and presentation separation: Markdown vs. theme/templates
• Immutable deploys: each build produces versioned static assets
• Micro-task pipelines: lint → build → deploy
• Resilience via CDN caching, fallback pages (404)
Technologies, frameworks, or libraries
• Markdown, SSG of choice (e.g., MkDocs/Jekyll)
• CI tool (GitHub Actions)
• Hosting (GitHub Pages or Netlify)
• Optional plugins (search, i18n, analytics)