How thinceller/blog.thinceller.net works
<explanation>
1. Project Type and Purpose
- This is a Jamstack‐style blog built with Next.js’s App Router, MDX for content, Chakra UI + Tailwind CSS for styling, and deployed as a serverless site on Cloudflare (using the open‑next adapter in wrangler.jsonc).
- Content lives in the _posts folder (MDX files). The React/TSX code lives under app and components. Build toolchain is configured via GitHub Actions, PostCSS, and open-next.config.ts.
2. Key Architectural Components
a. Source Control & CI/CD
- GitHub repo (code + MDXs + configs + ADRs)
- GitHub Actions workflows: linter, build, bundle analysis, preview, deploy
b. Build Pipeline
- Lint (Textlint, ESLint)
- TypeScript compilation & MDX bundling (with Shiki)
- CSS processing (Tailwind via PostCSS)
- Static site generation (SSG) + serverless SSR pages via open‑next adapter
c. Frontend Application
- Next.js App Router (app/): pages, layouts, dynamic routes
- React Components (components/), shared utilities (lib/)
- Styling: Chakra UI + global Tailwind CSS (styles/)
- MDX rendering (lib/mdx.tsx)
d. Deployment & Hosting
- Deployed to Cloudflare Workers/Pages via Wrangler (wrangler.jsonc)
- CDN caching sits in front of Workers, serving static assets from public/
e. External Services
- Google Analytics (gtag via lib/gtag.tsx)
- Brave Rewards verification (public/.well-known)
3. Relationships & Data Flow
1. Developer pushes to GitHub → triggers CI workflow
2. CI runs linters → runs Next.js build (TSX → JS, MDX → HTML)
→ bundles assets → PostCSS/Tailwind → outputs static files + SSR functions
3. On successful build → Deploy step pushes to Cloudflare Workers/Pages
4. End users hit the site URL → DNS→ Cloudflare CDN
• If cached static page/asset → return from edge
• Else → invoke Cloudflare Worker (SSR function) → render page → cache result
5. Analytics events fire from browser → Google Analytics
4. Architectural Patterns & Design Principles
- Jamstack: pre-rendered static pages + on‑demand serverless SSR
- File-based routing (Next.js App Router)
- Separation of concerns:
• Content (MDX) vs. UI components vs. utility libraries
• Build pipeline vs. runtime environment
- Use of ADRs (docs/adr/) to document decisions
- Infrastructure-as-code (wrangler.jsonc, GitHub workflow YAMLs)
5. Diagramming Guidelines
a. Components & Shapes
- Rectangle for “GitHub” (source + CI workflows)
- Gear/box for “Build Pipeline”
- Cylinder or hexagon for “Cloudflare CDN”
- Lambda icon or serverless shape for “Cloudflare Workers (SSR)”
- Browser icon for “End User Device”
- Cylinder for “Static Assets (public/, .well-known/)”
- Cylinder for “Content (MDX files in _posts)”
- External service cloud for “Google Analytics”
b. Relationships & Arrows
- Arrow from GitHub → Build Pipeline (“push → CI”)
- Arrow from Build Pipeline → Cloudflare Workers/Pages (“deploy”)
- Arrow from End User → CDN → Worker → End User (“request/response”)
- Arrow from Browser → GA (“analytics events”)
c. Colors & Labels
- Blue for code & content (repo, MDX, TSX)
- Green for build/deploy infrastructure (CI, Wrangler)
- Orange for runtime infra (Workers, CDN)
- Gray or neutral for external services
d. Legend & Annotations
- Legend box explaining shapes & colors
- Annotate where SSG vs. SSR happens
- Call out PostCSS/Tailwind & MDX bundling step
6. Tailoring to This Blog Project
- Emphasize the “MDX content → build time HTML” flow vs. on‑demand SSR routes (app/posts/[slug]).
- Highlight the open‑next adapter bridging Next.js SSR to Cloudflare Workers.
- Show how public/ maps directly to CDN static file hosting.
- Show CSS pipeline: Tailwind config → PostCSS → final CSS in build output.
By laying out these components, their interactions, and using clear labels, directional arrows, and color coding, you’ll create a precise system design diagram that captures the essential architecture of blog.thinceller.net without over‑complicating it.
</explanation>