How crytic/building-secure-contracts works
Project type and purpose
• This is a documentation-centric repository that uses Markdown and mdBook to build a static site (a learning “book”) covering best practices, EVM knowledge, common smart-contract pitfalls, and program-analysis tools.
• It’s not a running application or microservice cluster, but a content pipeline: authors write Markdown → mdBook compiles it → CI validates and deploys it → readers consume the static site.
File structure
• Top-level directories:
• development-guidelines, learn_evm, not-so-smart-contracts, program-analysis, resources – these are content modules (each one is a chapter/section).
• static – custom CSS/JS used by the mdBook theme.
• .github/workflows – CI/CD definitions for linting, analysis, fuzzers, deployment.
• book.toml, SUMMARY.md – mdBook config and site structure.
• Infrastructure files: package.json/lock if any JS scripts, .prettierrc for formatting, and CODEOWNERS/CONTRIBUTING for community workflow.
• Workflows use Slither, Echidna, Medusa, Manticore, plus link- and code-style checks. A deploy workflow publishes to hosting (GitHub Pages or similar).
README insights
• The README confirms the mdBook-based “book” structure, calls out each major section, and shows GitHub Action badges for analysis tools and deployment.
• No runtime services or databases are involved.
a. Content Repository (GitHub)
• Stores Markdown chapters, config files, static assets.
• Triggers CI workflows on push/PR.
b. CI/CD Pipeline (GitHub Actions)
• Lint & Format: linkcheck, markdown-lint, prettier.
• Static Analysis: Slither, Echidna, Medusa, Manticore (docs + example code tests).
• Build Step: mdBook compiler reads book.toml & SUMMARY.md + content, emits HTML/CSS/JS.
• Deploy Step: pushes built site to GitHub Pages / some hosting bucket.
c. Hosting Platform
• Serves the static website (GitHub Pages or S3+CloudFront).
d. End Users
• Web browsers rendering the static site with custom.css and script.js.
Relationships and interactions
• Developers commit Markdown; GitHub receives push → CI pipelines run in parallel (lint, analysis, build).
• Build produces an artifact (static site bundle); Deploy publishes it.
• Users send HTTP GET requests to the hosting endpoint → hosting platform returns the built assets.
• Optionally, third-party badges (Echidna/Slither status) are fetched by GitHub Actions and displayed in README.
Architectural patterns & design principles
• Content Pipeline: Separation of concerns—source content vs build vs deployment.
• Infrastructure-as-Code: CI workflows codify analysis, build, and deployment.
• Immutable Artifacts: Every build produces a versionable static bundle.
• Modular Documentation: The book is organized into independent chapters (folders), each of which can be updated, tested, and published in isolation.
Relevant technologies
• mdBook (rust-based static site generator).
• GitHub Actions (CI/CD).
• Slither, Echidna, Medusa, Manticore (program-analysis tools with example code).
• Markdown, CSS, JavaScript.
• GitHub Pages or equivalent static-site hosting.
Elements
• Clear labels for: Repository, CI Jobs (Lint, Static Analysis, Build, Deploy), Hosting, User.
• Repo → CI
• CI Build → Hosting
• Hosting → User
• Blue rectangles for services (GitHub Actions, Hosting)
• Orange parallelograms for external tools (Slither, Echidna, etc.)
• Rounded rectangles for users/developers.