System Design 101

This repository serves as a comprehensive introduction to the fundamental concepts and best practices required to excel as a system designer.

Explore the official site at this link.

---

Contribution Guide

We encourage contributions to help improve and expand this project!

Whether you're adding new contents, or refining documentation, feel free to open discussions or submit pull requests. Your input is invaluable!

Environment Setup

This project is built using the Hugo framework. To set up your environment, follow these steps:

Tools

Ensure the following tools are installed on your machine and properly configured:

• Golang
• Hugo
• D2

Make sure to set up environment variables to allow the tools to be called globally via go, hugo, and d2 commands.

Submodule

This project utilizes the Hextra theme. Initialize or update the theme module by running the following commands:

• For first-time setup:

  git submodule update --init --recursive

• To update the module when needed:

  git submodule update --recursive --remote

Render Diagrams with D2

This project relies on D2 for diagram creation. Since D2 diagrams aren’t natively supported, you’ll need to run a local renderer server in a separate process:

go run tools/d2_renderer.go

Build and Preview the Project

You can build and serve the project locally using the Hugo server:

hugo server

Refer to the Hugo documentation for available flags.

Content Structure

All content files are located in the content folder.

To ensure clean and readable documentation, please adhere to common markdown standards! If you're using VS Code, consider installing the Markdownlint extension to streamline linting.

Diagrams and Diagrams as Code

This project uses D2 to create diagrams such as architecture, sequence, or class diagrams.

When creating new diagrams, utilize D2 syntax for better modifiability and maintainability. Use the following syntax to define diagrams as code: ```d2 ```.

Predefined architectural components can be found in vars. To add a new component:

1. Place the image in the d2-icons folder.
2. Define a corresponding variable in vars.yaml.

Embedding Images

For faster loading and to prevent issues, download and use images locally (ensure that they are copyright-free):

• For images used infrequently:
  Create a folder specific to the topic and place the image directly within it.

• For shared/reusable images:
  Place the images in the images folder for universal access.

Multi-Language Support

Want to contribute content in another language? Follow the comprehensive Hextra theme instructions for multi-language support to set up translations effectively.