# crytic/building-secure-contracts architecture

> Architecture diagram of the GitHub repository crytic/building-secure-contracts, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/crytic/building-secure-contracts
- Repository: https://github.com/crytic/building-secure-contracts

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    Dev("Developers"):::actor

    %% Version Control
    subgraph "Version Control"
        direction TB
        CR["Content Repository"]:::services
        subgraph "Content Modules"
            direction TB
            DG["development-guidelines/"]:::artifacts
            LE["learn_evm/"]:::artifacts
            NS["not-so-smart-contracts/"]:::artifacts
            PA["program-analysis/"]:::artifacts
            RE["resources/"]:::artifacts
        end
        subgraph "Config & Metadata"
            direction TB
            BT["book.toml"]:::artifacts
            SM["SUMMARY.md"]:::artifacts
            RD["README.md"]:::artifacts
            PR[".prettierrc"]:::artifacts
            PJ["package.json"]:::artifacts
            PL["package-lock.json"]:::artifacts
        end
    end

    %% CI/CD Pipeline
    subgraph "CI/CD Pipeline"    
        direction TB
        LF["Lint & Format"]:::services
        LL["Link Checking"]:::services
        subgraph "Static Analysis"
            direction TB
            SL["Slither"]:::tools
            EC["Echidna"]:::tools
            MD["Medusa"]:::tools
            MT["Manticore"]:::tools
            subgraph "Echidna Examples"
                direction TB
                PAE["program-analysis/echidna/"]:::artifacts
                MEJ["medusa.json"]:::artifacts
            end
            subgraph "Manticore Docs"
                direction TB
                MDOC["program-analysis/manticore/"]:::artifacts
            end
        end
        BD["Build (mdBook)"]:::services
        DP["Deploy"]:::services
        subgraph "Static Assets"
            direction TB
            CSS["static/custom.css"]:::artifacts
            JS["static/script.js"]:::artifacts
        end
    end

    %% Hosting & Users
    HO["Hosting Platform"]:::services
    US["End Users (Browser)"]:::actor

    %% Connections
    Dev --> CR
    CR --> LF
    CR --> LL
    CR --> SL
    CR --> EC
    CR --> MD
    CR --> MT
    CR --> BD
    CR --> DP

    SL --> BD
    EC --> BD
    MD --> BD
    MT --> BD
    LF --> BD
    LL --> BD

    BD --> DP
    DP --> HO
    HO --> US

    %% Click Events - Repository
    click DG "https://github.com/crytic/building-secure-contracts/tree/master/development-guidelines/"
    click LE "https://github.com/crytic/building-secure-contracts/tree/master/learn_evm/"
    click NS "https://github.com/crytic/building-secure-contracts/tree/master/not-so-smart-contracts/"
    click PA "https://github.com/crytic/building-secure-contracts/tree/master/program-analysis/"
    click RE "https://github.com/crytic/building-secure-contracts/tree/master/resources/"
    click BT "https://github.com/crytic/building-secure-contracts/blob/master/book.toml"
    click SM "https://github.com/crytic/building-secure-contracts/blob/master/SUMMARY.md"
    click RD "https://github.com/crytic/building-secure-contracts/blob/master/README.md"
    click PR "https://github.com/crytic/building-secure-contracts/blob/master/.prettierrc"
    click PJ "https://github.com/crytic/building-secure-contracts/blob/master/package.json"
    click PL "https://github.com/crytic/building-secure-contracts/blob/master/package-lock.json"
    click CR "https://github.com/crytic/building-secure-contracts/blob/master/."

    %% Click Events - CI Workflows
    click LF "https://github.com/crytic/building-secure-contracts/blob/master/.github/workflows/lint_format.yml"
    click LL "https://github.com/crytic/building-secure-contracts/blob/master/.github/workflows/lint_links.yml"
    click EC "https://github.com/crytic/building-secure-contracts/blob/master/.github/workflows/echidna.yml"
    click MD "https://github.com/crytic/building-secure-contracts/blob/master/.github/workflows/medusa.yml"
    click MT "https://github.com/crytic/building-secure-contracts/blob/master/.github/workflows/manticore.yml"
    click DP "https://github.com/crytic/building-secure-contracts/blob/master/.github/workflows/deploy.yml"

    %% Click Events - Static Analysis Examples
    click PAE "https://github.com/crytic/building-secure-contracts/tree/master/program-analysis/echidna/"
    click MEJ "https://github.com/crytic/building-secure-contracts/blob/master/program-analysis/echidna/example/medusa.json"
    click MDOC "https://github.com/crytic/building-secure-contracts/tree/master/program-analysis/manticore/"

    %% Click Events - Static Assets
    click CSS "https://github.com/crytic/building-secure-contracts/blob/master/static/custom.css"
    click JS "https://github.com/crytic/building-secure-contracts/blob/master/static/script.js"

    %% Styles
    classDef services fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef artifacts fill:#90EE90,stroke:#000,stroke-width:1px
    classDef tools fill:#FFA500,stroke:#000,stroke-width:1px
    classDef actor fill:#D3D3D3,stroke:#000,stroke-width:1px
```
