How datawhalechina/intro-mathmodel works
1. Repository role
- This repo is not an application backend; it is a static course/documentation site for “数学建模导论【🧪 Beta公测版】”.
- Its main purpose is to publish a structured set of teaching chapters on math modeling, Python-based modeling techniques, and related data science methods.
2. Top-level architecture
- The meaningful runtime boundary is the docs/ site root.
- README.md is the project landing page for GitHub and also describes the curriculum scope.
- docs/index.html, docs/_sidebar.md, and docs/.nojekyll indicate the repo is designed for static hosting on GitHub Pages.
3. Primary content layer
- The core content is organized into chapter folders under docs/CH0 through docs/CH10.
- Each chapter folder contains one main markdown article, e.g. chapter pages like:
- docs/CH1/第1章-解析几何与方程模型.md
- docs/CH9/第九章-机器学习与统计模型.md
- This is the main source of truth for the book’s narrative and learning progression.
4. Navigation and site shell
- docs/_sidebar.md is the site navigation layer that ties the chapter pages together.
- docs/index.html acts as the front page / host shell for the documentation site.
- The site is therefore built around a sidebar-driven documentation layout, not a code-driven app UI.
5. Chapter-level boundaries
- The chapters are logically separated by modeling domain:
- geometry and equations
- differential equations and dynamical systems
- optimization and planning
- graph/network models
- evolutionary and swarm algorithms
- data processing and fitting
- evaluation/weighting methods
- time series and investment
- machine learning and statistics
- multimodal data and intelligent models
- This separation is important for architecture diagrams because each chapter is an independent content module rather than a tightly coupled code package.
6. Supplementary assets
- Several chapter folders include attachments/, attachment/, or src/ subfolders.
- These hold supporting materials such as figures, example data, code snippets, or source artifacts used in the chapter pages.
- The content flow is: chapter markdown references local assets inside the same chapter directory.
7. Mixed source formats
- Most chapter content is in Markdown, but some chapters also contain .docx files.
- This suggests a documentation workflow where Word drafts or editorial source material coexist with Markdown publication files.
- For architecture, treat .docx as authoring/support artifacts, not primary runtime content.
8. Publication/deployment model
- The presence of .nojekyll strongly suggests the docs are published as a static site without Jekyll processing.
- The likely deployment target is GitHub Pages, as hinted by the project URL in the README.
- There is no evidence of a server-side application, database, or API layer.
9. Technology footprint
- The repo is documentation-first, but the subject matter references Python tooling throughout the course, including NumPy, SciPy, SymPy, Pandas, Matplotlib, NetworkX, cvxpy, scikit-learn, and PyTorch.
- These libraries are part of the course content/examples, not necessarily runtime dependencies of the site itself.
- The site layer itself is mostly static HTML + Markdown.
10. Content flow
- Authoring likely happens in chapter markdown and supporting files inside each CH* folder.
- The chapter pages are linked through the sidebar and rendered by the static site shell.
- Readers interact only with the published documentation site; there is no interactive backend data flow.
11. Repository boundary to note in a diagram
- Everything under docs/ belongs to the publishable documentation system.
- README.md is the repo-level introduction and contribution entry point.
- External services are limited to GitHub hosting/pages and the project website; no other infrastructure is implied by the file tree.
12. How to diagram it
- Draw one large boundary for the repo.
- Inside it, show a static docs site with:
- site shell/navigation (index.html, _sidebar.md)
- chapter content modules (CH0–CH10)
- chapter assets/source artifacts (attachments, src, .docx)
- Then show publication to a static hosting target, with readers consuming the rendered documentation.
Main entry points: _sidebar.md Sidebar · index.html Home page · 第1章-解析方法与几何模型.md 解析几何 · 第2章-微分方程与动力系统.md 微分方程
Components 20
Repository
Project landing and source materials
- README · Repo-level introduction and course overview
README.md
Static site
Publishable documentation shell under docs/
- Docs README · Landing page for the documentation subtree
docs/README.md - Home page · Static docs front page
docs/index.html - Sidebar · Chapter navigation for the site
docs/_sidebar.md - No Jekyll · Disables Jekyll processing for static hosting
docs/.nojekyll
Chapter content
Course chapters and supporting assets
- 绪论 · Introductory modeling overview
docs/CH0/绪论-走进数学建模的大门.md - 解析几何 · Analytic methods and geometry models
docs/CH1/第1章-解析方法与几何模型.md - 微分方程 · Differential equations and dynamical systems
docs/CH2/第2章-微分方程与动力系统.md - 规划模型 · Extremum and optimization models
docs/CH3/第三章-函数极值与规划模型.md - 图论网络 · Complex networks and graph models
- 进化计算 · Evolutionary computation and swarm intelligence
docs/CH5/第五章-进化计算与群体智能.md - 数据拟合 · Data processing and curve fitting
docs/CH6/第六章-数据处理与拟合模型.md - 评价模型 · Weighting and evaluation methods
docs/CH7/第7章-权重生成与评价模型.md - 时间序列 · Time series and investment models
docs/CH8/第8章-时间序列.md - 机器学习 · Machine learning and statistics
docs/CH9/第九章-机器学习与统计模型.md - 多模态数据 · Image, text, and signal data modeling
docs/CH10/第10章-图像、文本与信号数据.md - Chapter assets · Figures, data, and embedded chapter resources
docs/CH1/attachments - Authoring sources · Word drafts and source artifacts mixed with markdown publications
docs/CH7/第7章-评价类模型.docx
Hosting
Static publication target
- GitHub Pages · Static publication target for the docs site
- Readers · Users consuming the rendered course site
Connections 34
- README → Docs README: describes · Repository landing page introduces the docs site
- Docs README → Home page: points to · Docs landing content leads into the site shell
- Home page → Sidebar: uses · Front page relies on sidebar-driven navigation
- Sidebar → 绪论: links · Navigation connects the chapter sequence
- Sidebar → 解析几何: links · Navigation connects the chapter sequence
- Sidebar → 微分方程: links · Navigation connects the chapter sequence
- Sidebar → 规划模型: links · Navigation connects the chapter sequence
- Sidebar → 图论网络: links · Navigation connects the chapter sequence
- Sidebar → 进化计算: links · Navigation connects the chapter sequence
- Sidebar → 数据拟合: links · Navigation connects the chapter sequence
- Sidebar → 评价模型: links · Navigation connects the chapter sequence
- Sidebar → 时间序列: links · Navigation connects the chapter sequence
- Sidebar → 机器学习: links · Navigation connects the chapter sequence
- Sidebar → 多模态数据: links · Navigation connects the chapter sequence
- 解析几何 → Chapter assets: references · Chapter pages pull in local supporting material
- 微分方程 → Chapter assets: references · Chapter pages pull in local supporting material
- 数据拟合 → Chapter assets: references · Chapter pages pull in local supporting material
- 评价模型 → Authoring sources: includes · Markdown and Word drafts coexist in chapter folders
- 时间序列 → Authoring sources: includes · Markdown and Word drafts coexist in chapter folders
- 机器学习 → Authoring sources: includes · Markdown and Word drafts coexist in chapter folders
- No Jekyll → GitHub Pages: enables · Static hosting without Jekyll transforms
- Home page → GitHub Pages: publishes to · Rendered documentation is deployed to static hosting
- GitHub Pages → Readers: serves · Readers access the published documentation site
- 绪论 → Readers: consumed by · Course content is read through the published site
- 解析几何 → Readers: consumed by · Course content is read through the published site
- 微分方程 → Readers: consumed by · Course content is read through the published site
- 规划模型 → Readers: consumed by · Course content is read through the published site
- 图论网络 → Readers: consumed by · Course content is read through the published site
- 进化计算 → Readers: consumed by · Course content is read through the published site
- 数据拟合 → Readers: consumed by · Course content is read through the published site
- 评价模型 → Readers: consumed by · Course content is read through the published site
- 时间序列 → Readers: consumed by · Course content is read through the published site
- 机器学习 → Readers: consumed by · Course content is read through the published site
- 多模态数据 → Readers: consumed by · Course content is read through the published site