kamranahmedse/developer-roadmap

Overview

The kamranahmedse/developer-roadmap repository powers roadmap.sh, a community-driven platform providing interactive roadmaps, best practices, and resources for developers. Its primary goal is to help developers and aspiring technologists navigate learning paths in various fields such as frontend, backend, DevOps, AI, and more. The platform features visually engaging, interactive roadmaps, curated best practices, quizzes, and guides, all contributed by a global community.

Architecture

The project is a modern, full-stack web application built primarily with Astro as the static site generator and React for dynamic, interactive components. The architecture leverages a monorepo structure (see pnpm-workspace.yaml) and integrates a variety of scripts for content management, asset generation, and automation. Content is organized in a structured directory format under src/data/roadmaps and src/data/best-practices, with each roadmap or best practice having its own directory containing metadata, content, and assets. The site is styled using Tailwind CSS, and uses Playwright for end-to-end testing.

Key architectural highlights:

• Astro: Handles static site generation, server-side rendering, and integration of React components.
• React: Powers interactive roadmap editors and dynamic UI elements.
• Content Sourcing: Markdown files and JSON data define roadmap nodes, best practices, and guides. Scripts automate content generation, validation, and transformation.
• Automations: Node.js and TypeScript scripts manage content directories, compress images, generate Open Graph images, and synchronize content with external APIs.
• Testing: Playwright is used for automated browser testing.

Key Features

• Interactive Roadmaps: Users can explore, click, and expand roadmap nodes to learn about specific topics. Each node links to curated resources and concise explanations.
• Best Practices: Dedicated sections for backend, frontend, API security, AWS, and more, with structured content and actionable advice.
• Questions & Quizzes: Self-assessment tools to help users gauge their knowledge in various domains.
• Content Automation: Scripts for generating, validating, and cleaning up content, including AI-assisted content creation (OpenAI/Gemini integration for topic explanations).
• Open Graph Image Generation: Automated scripts generate visually consistent OG images for sharing on social media.
• Community Contributions: Clear guidelines and tooling for adding new roadmaps, improving content, and contributing resources.

Project Structure

Path/Directory	Purpose
src/data/roadmaps	Contains all roadmap definitions, content, and metadata.
src/data/best-practices	Contains best practice guides and content.
scripts/	Automation scripts for content, assets, and maintenance tasks.
public/	Static assets (images, OG images, PDFs, etc.).
astro.config.mjs	Main Astro configuration, including plugins and SSR settings.
tailwind.config.cjs	Tailwind CSS configuration.
package.json	Project dependencies and scripts.
playwright.config.ts	Playwright test configuration.

How It Works

1. Content Management: Roadmaps and best practices are defined as Markdown and JSON files. Scripts in the scripts/ directory automate directory creation, content population (including AI-generated summaries), and cleanup of orphaned files.
2. Build Process: Astro compiles the site, integrating React components for interactivity. Tailwind CSS provides styling, and various plugins (e.g., for Markdown, sitemaps, and OG images) enhance the build.
3. Deployment: The site can be deployed as a standalone Node.js server or as static files. Scripts support deployment to GitHub Pages and other platforms.
4. Contribution Workflow: Contributors can add or update roadmaps, suggest resources, or improve best practices by following guidelines in contributing.md.

The repository is a robust, scalable, and community-friendly platform for developer education, with a strong focus on automation, maintainability, and user experience.