How golang101/golang101 works
<explanation>
1. Project Type and Purpose
- This is a Go‑based static‑site generator and local HTTP server (“golang101” command) for hosting the “Go语言101” documentation series.
- It combines a CLI entry point, a built‑in HTTP server, file‑system or embedded content providers, template rendering, and static asset delivery.
2. Top‑Level Files and Folders
- go.mod, go.sum: module and dependency management.
- main.go, gen.go, redirects.go: CLI, build‑time generation, HTTP routing/redirect logic.
- golang101‑embed.go / golang101‑notembed.go: two compilation modes—content embedded vs. read from disk.
- pages/: Markdown‑to‑HTML content for each chapter/section.
- web/templates/: HTML templates for articles and redirects.
- web/static/: CSS, JS, fonts, images (Bootstrap, code syntax highlighters, etc.).
- net_*.go: OS‑specific network listener wrappers.
3. Key Architectural Patterns
- Monolithic HTTP server with modular handlers (Controller).
- MVC‑style separation:
• Model: raw page files (pages/), static assets (web/static/)
• View: Go HTML templates (web/templates/)
• Controller: HTTP handlers in main.go and redirects.go
- Build‑time code generation (gen.go) to produce the embed vs. no‑embed variants.
- Use of Go’s embed package (in embed mode) or os.File operations (non‑embed).
4. Main Components (Boxes in Diagram)
A. CLI & Configuration
- golang101 command
- Flags: –port, –theme
B. HTTP Server
- net.Listen (net_*.go)
- http.ServeMux / router
C. Handlers
1. Static File Handler
• Serves /static/* from embedded FS or disk
2. Content Handler
• Parses URL → maps to pages/… .html/.md
• If .md → Markdown‑to‑HTML conversion (built‑in)
• Renders via Templates
3. Redirect Handler
• redirects.go: maps legacy URLs to current pages
D. Content Providers
- Embedded FS (golang:embed) or os.DirFS
- pages/ and web/static/ treated as virtual file systems
E. Template Engine
- web/templates/article/*.tmpl
- web/templates/redirect/*.tmpl
5. Relationships and Data Flows (Arrows)
1. User CLI Invocation → Main
2. Main → Load Configuration & Content Provider (Embed vs Disk)
3. Main → Start HTTP Server → Listen on Port
4. Incoming HTTP Request → Router → Appropriate Handler
5. Handler → Read File from FS → [If Markdown] Convert → Inject into Template → HTTP Response
6. Static Handler → Serve Asset → HTTP Response
6. Technology Stack Callouts
- Go 1.16+ toolchain with embed
- net/http standard library
- go.mod dependency management
- Third‑party JS/CSS: Bootstrap, Prism, code‑prettify
7. Diagram‑Drawing Guidelines
- Use distinct shapes/colors:
• Blue boxes for external/user interfaces (CLI, Browser)
• Green for core services (HTTP Server, Handlers)
• Yellow for content stores (Embedded FS, pages/, static/)
• Orange for templates and rendering
- Label arrows with action names (e.g., “HTTP Request,” “Read File,” “Render Template,” “HTTP Response”).
- Group related components into swimlanes:
• Build‑time (gen.go → embed code generation)
• Runtime (HTTP server, handlers, FS, templates)
8. Tailoring Tips
- Emphasize separation of concerns: CLI vs. server vs. content vs. templates.
- Highlight embed vs. disk mode as a configuration decision at startup.
- Show how pages/ folder structure (fundamentals, generics, optimizations, etc.) maps to URL paths and handler logic.
9. Essential Elements to Include
- Clear, self‑explanatory labels for each box.
- Directional arrows for data/control flow.
- Legend or color key to distinguish component categories.
- Note on platform‑specific net_*.go that factored OS compatibility into server setup.
By following this breakdown and visualizing each component and their interactions, you will produce a precise, detailed architecture diagram of the golang101 project without omitting any core elements.