feat: update Docusaurus configuration, add project description, and introduce new documentation topics

Author: ghanem-mhd

.cursor/rules/project-description.mdc

@@ -0,0 +1,7 @@
+---
+description: 
+globs: 
+alwaysApply: false
+---
+This project is a content-driven documentation website built with Docusaurus. It serves as a technical roadmap for developers in Syria, offering curated guidance across various domains of software development. The site includes structured pages on key topics such as web development, data structures, DevOps, system design, and more. Each topic features resource links, learning paths, and contextual explanations tailored to the local challenges and opportunities of Syrian developers. The goal is to create an accessible, evolving reference for anyone seeking to grow as a developer under constrained circumstances.
+

docs/faq/README.md

@@ -0,0 +1,6 @@
+---
+sidebar_position: 3
+title: FAQ
+---
+
+# Frequently Asked Questions

docs/getting-started/README.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 1
+---
+
+# Getting Started
+
+## What is xxx?
+
+## For who?

docs/intro.md

@@ -0,0 +1,86 @@
+---
+sidebar_position: 1
+---
+
+# Web
+
+## Why it matters
+
+Whether you're building a mobile app, a complex backend system, or a beautiful frontend, you're working with the web. Understanding its fundamental principles is not just for "web developers"—it's for **every developer**. This knowledge helps you diagnose problems faster, build more efficient applications, and collaborate effectively with your team.
+
+When your mobile app can't connect to the server, knowing how HTTP requests work helps you find the bug. When your website is slow, understanding hosting and CDNs helps you speed it up. Think of it as the foundation of a building: without a solid one, everything you build on top is at risk.
+
+## What is expected from you
+
+As a developer, you are expected to have a clear mental model of how a user's action (like clicking a link) results in a fully loaded application on their screen. This means you should be able to:
+
+- Explain the lifecycle of a web request.
+- Describe different ways to host and deploy a simple web project.
+- Understand how a client application (web or mobile) connects to a backend.
+- Define what an API is and what it's used for.
+- Explain how a CDN helps improve application performance.
+
+### Internet Fundamentals
+
+A solid grasp of the web's **request-response model** is one of the most critical skills for a developer, as it's the foundation for all communication over the network. Understanding this cycle is essential for diagnosing issues, optimizing performance, and building secure applications.
+
+The process involves a few key technical components working in sequence:
+
+- **DNS (Domain Name System):** The process starts with a DNS lookup to resolve a human-readable domain name (e.g., `roadmap.sh`) into a server's IP address.
+- **HTTP/S Request:** The client (like a browser or mobile app) sends an **HTTP** request to that IP address. This request specifies a method (`GET`, `POST`, etc.), headers (containing metadata), and an optional body (containing data).
+- **HTTP/S Response:** The server processes the request and returns an HTTP response, which includes a **status code** (`200 OK`, `404 Not Found`, `500 Internal Server Error`, etc.), headers, and an optional body containing the requested resource (like HTML or JSON).
+
+For a developer, mastering this flow is non-negotiable. When an application fails, is it a DNS issue? A malformed client request? A server-side bug returning a `500` error? Or a network problem? By using your browser's network inspection tools, you can see this entire cycle in action, analyze headers, check status codes, and pinpoint exactly where things went wrong. This knowledge also allows you to optimize performance by reducing request payloads or to implement security features by manipulating HTTP headers.
+
+### Hosting & Deployment
+
+Code on your local machine is invisible to the world. The essential skill of **deployment** is what makes your application public. As a developer, you're expected to understand how to take a project from your computer to a live, accessible server.
+
+A great starting point is using modern deployment platforms like **Netlify**, **Vercel**, or **GitHub Pages**. These services are excellent for a few reasons:
+
+- They teach you the critical, modern workflow of deploying directly from a Git repository.
+- They handle the complex parts for you, allowing you to get your projects online quickly and build confidence.
+
+However, it's important to recognize that these platforms intentionally **hide the details**. As you advance, you must look inside this "black box." A proficient developer should eventually understand the concepts that these platforms manage automatically:
+
+- What a Web Server is (e.g., Nginx or Apache) and how it handles requests.
+- The basics of a Linux server environment.
+- How SSL certificates are provisioned and renewed for HTTPS.
+- How to set up a build pipeline to compile your code on a server.
+
+Think of it as a learning journey. Start with the automated platforms to master the modern deployment _workflow_. As you grow, the next step is to manually deploy a project to understand what's happening underneath. This is where you'll encounter the traditional hosting options: from basic Shared Hosting, to a more hands-on VPS (Virtual Private Server), and eventually the powerful environments offered by Cloud Hosting providers.
+
+### The Backend & APIs
+
+For many client-side developers, the backend can feel like a black box. You send a request and get a response, but what happens in between? Understanding the server's inner workings is a superpower; it helps you debug issues faster, collaborate more effectively, and build more resilient applications without having to "wait for the backend team."
+
+The relationship starts with the **client-server architecture**. Your frontend or mobile app is the **client**, responsible for the user interface. The **backend** is the authoritative server that handles the heavy lifting. This separation is powerful because it allows multiple different clients (web, iOS, Android) to connect to a single, consistent source of logic and data.
+
+The bridge between these two worlds is the **API (Application Programming Interface)**. It's a formal contract that defines the rules of communication. Most modern APIs are **REST APIs**, which use standard HTTP methods and **JSON** to create, retrieve, update, or delete data.
+
+So, when your app sends an API request, what's actually happening inside that "black box"? Typically, a few things:
+
+1. **Authentication & Authorization:** The first thing the backend often does is check _who you are_ and _what you're allowed to do_. It inspects the request, often looking for an `Authorization` header containing a token (like a JWT). This step determines if the request should proceed or be rejected with a `401 Unauthorized` or `403 Forbidden` error.
+
+2. **Business Logic Execution:** This is the "brain" of the backend. It's the code that receives your request and performs the core task. For example, if you're building an e-commerce app, the business logic might validate that an item is in stock, calculate the total price with taxes, and apply a discount code.
+
+3. **Database Interaction:** Business logic almost always requires interacting with a database. The backend code will run queries to fetch the data you requested (e.g., a user's profile) or write new data that you sent (e.g., a new comment on a post).
+
+As a client-side developer, you don't need to _write_ this backend code, but knowing it exists is crucial. When you get a `400 Bad Request` error, you can guess that your app sent invalid data that failed the business logic validation. If you get a `500 Internal Server Error`, you know the problem is likely on the server itself—perhaps a database connection failed. This understanding allows you to read API documentation (like Swagger/OpenAPI specs) effectively and handle responses gracefully, making you a far more independent and capable developer.
+
+## Resources
+
+### English Resources
+
+- [📚 How does the Internet Work?](https://cs.fyi/guide/how-does-internet-work)
+
+### Arabic Resources
+
+- [🎥 كيف يعمل الإنترنت؟](https://youtu.be/TnMNDQHB33Q?si=--tU7Y7iS3uWw8fU)
+- [مفاهيم برمجية - by أكاديمية ترميز](https://youtube.com/playlist?list=PLYyqC4bNbCIepFULT9gvCcaQR35lUZbXT&si=dMBXgVbR7OkXc-oH)
+- [🎥 كل ما تحتاج معرفته عن الـ SSL || تأمين المواقع على الإنترنت](https://youtu.be/9EOdDUmAErQ?si=X0CslAQvJpWlWgHm)
+- [🎥 الفرق بين http و https | بالتفصيل و بالرسومات التوضيحية](https://youtu.be/2wH6c4HQDcA?si=GDaNW87-n4VGMxo0)
+- [🎥 Deal With Hosting - Elzero Web School](https://youtube.com/playlist?list=PLDoPjvoNmBAxWdsGkG_o3_ULQQw2GtnyS&si=hqc1_QwqRQVuay8F)
+- [🎥 الاستضافة بدون سيرفر | Serverless Hosting (Arabic) 😶‍🌫️🌨️](https://youtu.be/2oBFrZ1fE3U?si=Dafj4Dog0BEClwPC)
+- [يعني إيه API؟ وإزاي بتشتغل؟ الفرق بينها وبين Web API ببساطة](https://youtu.be/FGwPNrrnfBw?si=gDPP6cfkZ8l6m5n0)
+- [What is Web API?](https://youtu.be/MRBTDYNKGLo?si=I6aV-oaOXG7UGfqA)

docs/topics/1-web.md

@@ -0,0 +1,82 @@
+---
+sidebar_position: 2
+---
+
+# Git
+
+You've written some great code and saved the file. Maybe you even zipped the project folder and named it project-final-v2-really-final.zip as a backup. Your work is safe and you're ready to share it with the team, right? Not quite. That old habit of manually managing versions is a recipe for confusion and lost work in any professional team.
+
+## Why it matters
+
+In modern software development, working in a team is the norm. Git is the industry-standard tool for version control, allowing multiple developers to collaborate on the same codebase without stepping on each other's toes. Think of it as a "save" button for your entire project, but with powerful features: it tracks every change, lets you experiment with new ideas on separate "branches," and helps you merge your work back with your team's. Mastering Git is a fundamental skill that makes you a more effective engineer. It’s a gateway to contributing to open-source projects and working with remote teams anywhere in the world. It provides a safety net for your code and a transparent history of your project's evolution, which is invaluable for maintenance and debugging.
+
+## What is expected from you
+
+As a developer, you are expected to be comfortable with the daily commands and collaborative workflows that Git enables. While you don’t need to be a Git guru who has memorized every command, you should have a solid grasp of the essentials to work efficiently in a team environment.
+
+### Git Basics
+
+You need to understand the Git basics because you will use them almost every day. These concepts form the foundation of your interaction with any codebase under version control.
+
+- **Repository (Repo)**: This is the main folder for your project. The repo contains all your project files and, most importantly, a hidden sub-folder named `.git` that stores the entire history of changes.
+- **Commit**: A commit is a snapshot of your repository at a specific point in time. When you `commit` your work, you are saving your staged changes along with a message describing what you did.
+- **Branch**: A branch is a parallel version of your repository. You create branches to work on new features or bug fixes in isolation without affecting the main codebase (often called the `main` or `master` branch). Imagine it as a separate timeline where you can experiment freely.
+- **Push**: This is how you send your committed changes from your local repository on your computer to a remote repository (like one hosted on GitHub). This makes your changes available to your teammates.
+- **Pull**: This is how you fetch changes from a remote repository and merge them into your local repository. You `pull` to make sure your local version is up-to-date with the latest changes from your team.
+
+### Branching Strategies & Workflows
+
+A branching strategy is simply your team's set of rules for managing branches. You don’t have to be an expert on every detail, but it’s important to know that these strategies exist and to grasp their core ideas. They bring order to the development process, ensuring everyone knows how to contribute work safely without creating chaos. The strategy a team uses depends on its project size, release frequency, and overall workflow, so understanding the common patterns will help you adapt quickly in any professional environment.
+
+- **[Gitflow Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow)**: This is a robust and structured workflow that uses long-running branches like `main` and `develop`, along with supporting branches for features, releases, and hotfixes (`feature`, `release`, `hotfix`). It's great for projects with scheduled releases but can be complex for simpler projects.
+- **[Feature Branch Workflow](https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow)**: This is a simpler and very common approach. The core idea is that all new development happens in a dedicated `feature` branch instead of directly on the `main` branch. Once the feature is complete, it is merged into `main`. This keeps your primary branch clean and stable.
+- **[GitHub Flow](https://docs.github.com/en/get-started/quickstart/github-flow)**: A lightweight workflow perfect for teams that practice continuous deployment. You create a branch from `main` for any change (feature or fix), push it to the remote, and open a Pull Request. After review and testing, it's merged into `main` and deployed immediately.
+- **[Trunk-Based Development](https://trunkbaseddevelopment.com/)**: In this strategy, developers commit directly into a single shared branch, often called `trunk` (or `main`). To avoid instability, changes are usually small and integrated frequently. This model relies heavily on strong automated testing to ensure the trunk is always releasable.
+
+### Collaboration
+
+Git is built for collaboration. These practices are key to working effectively with other developers.
+
+- **[Pull Requests (PRs)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) / [Merge Requests (MRs)](https://docs.gitlab.com/user/project/merge_requests/)**: This is the heart of collaboration. Instead of pushing your changes directly into the main branch, you create a Pull Request (on GitHub/Bitbucket) or Merge Request (on GitLab). This acts as a formal proposal to merge your work. It allows your teammates to see your changes, discuss them, and suggest improvements before they are integrated.
+- **Handling Merge Conflicts**: A merge conflict happens when Git can't automatically merge two branches because they both have conflicting changes on the same line of a file. You will inevitably face these. The key is not to panic. Your editor will show you exactly where the conflicts are, and you simply need to edit the file to keep the version you want (yours, the other person's, or a combination of both), then commit the resolved file.
+- **Commit Messages**: Clear commit messages are crucial for a healthy project. They provide context for your changes, making it easier for others (and your future self) to understand the history of the codebase. A common practice is to follow the **[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)** specification, which provides a simple set of rules for creating an explicit commit history.
+
+## Resources
+
+### English Resources
+
+### Arabic Resources
+
+- [ماهو Github جيت هب؟ وما أهميته لكل مبرمج؟](https://youtu.be/PsXDzwBW2Ls?si=hK_rA1NGhTdJc533)
+
+## 🎥 Video Resources
+
+2. [Git for Beginners](https://youtu.be/fDkR0TDR9dI?si=Y2ZPKHev0nnWd-ur)
+3. [Git Tutorial by IBM Technology](https://www.youtube.com/watch?v=wpISo9TNjfU&ab_channel=IBMTechnology)
+4. [Git & GitHub for Beginners by Mosh](https://www.youtube.com/watch?v=8JJ101D3knE&ab_channel=ProgrammingwithMosh)
+5. [Another Git Video](https://youtu.be/HkdAHXoRtos?si=h2c6u1YUTnaIAkjT)
+
+---
+
+## 📚 YouTube Playlists
+
+6. [Git & GitHub Tutorials (Playlist 1)](https://youtube.com/playlist?list=PL4n1Qos4Tb6R4guGC4oX_PZVt8E8XpvqE&si=gTyfVKZ9jgbW_wN0)
+7. [Git & GitHub Tutorials (Playlist 2)](https://www.youtube.com/playlist?list=PLYyqC4bNbCIeCHLTRtwdLpQvle_zIavZ-)
+8. [Git Tutorials by Elzero Web School](https://www.youtube.com/playlist?list=PLDoPjvoNmBAw4eOj58MZPakHjaO3frVMF)
+
+---
+
+## 📝 Readable Resources
+
+9. [How to Use GitHub Website (ar-wp.com)](https://www.ar-wp.com/how-to-use-github-website/)
+10. [What is Git? Quick Tutorial for Beginners (pyarabic.com)](https://pyarabic.com/what-is-git-quick-tutorial-for-beginners/)
+11. [Best Practices for Writing Clean Commits in Git (eqraatech.com)](https://eqraatech.com/best-practices-for-writing-clean-commits-in-git/)
+12. [Git Commit Message Cheatsheet (eqraatech.com)](https://eqraatech.com/git-commit-message-cheatsheet/)
+13. [Git & GitHub Roadmap](https://roadmap.sh/git-github)
+
+---
+
+## 🕹️ Interactive Tutorials
+
+14. [Oh My Git!](https://ohmygit.org/)
+15. [Learn Git Branching](https://learngitbranching.js.org/)