# ahmed-abdelwahed1/personal-website architecture

> Architecture diagram of the GitHub repository ahmed-abdelwahed1/personal-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ahmed-abdelwahed1/personal-website
- Repository: https://github.com/ahmed-abdelwahed1/personal-website

## Overview

1. This repository is a single Next.js App Router application for a personal portfolio plus technical blog. The app shell is centered in `src/app/layout.tsx`, with the homepage at `src/app/page.tsx` and blog routes under `src/app/blog`.

2. The site is mostly static and content-driven. Most page content comes from local files under `content/`, not from a database or external CMS at runtime. JSON files model structured profile data, while Markdown files power the blog.

3. The homepage assembles several presentation sections from reusable React components in `src/components/` such as Hero, Experience, Projects, Education, Badges, Volunteering, and GitHub heatmap. These sections are fed by `src/lib/content.ts`, which is the main boundary between UI and structured content.

4. The blog is a separate content pipeline. `src/lib/blog.ts` reads Markdown posts from `content/blog/`, and the blog index plus dynamic post pages render that parsed content. This is where the main “content ingestion → page rendering” flow happens.

5. SEO and metadata are first-class concerns. The app includes sitemap generation (`src/app/sitemap.ts`), `robots.txt`, and structured data components such as `JsonLd` and `BlogPostJsonLd`. Blog pages also use reading-progress and tracker components to support article UX and analytics-like behavior.

6. The app shell also establishes global client behavior: theme handling via `ThemeProvider` and `ThemeToggle`, plus optional motion-enhanced UI through `AnimatedSection` and other Framer Motion-backed components. These are client-side concerns layered on top of otherwise static content rendering.

7. Deployment and runtime configuration are Netlify-specific. `netlify.toml` defines hosting behavior, and `netlify/edge-functions/markdown-negotiation.ts` adds an edge-layer content negotiation path so requests with `Accept: text/markdown` can receive Markdown instead of HTML.

8. The repository includes a notable “agent readiness” subsystem under `public/.well-known/`. These files expose discovery metadata for API catalogs, agent skills, MCP server cards, and OAuth/OpenID metadata, making the site machine-discoverable beyond normal browser traffic.

9. The homepage and public assets are also designed for agent/browser tool access. The layout registers WebMCP-related capabilities, while `public/.well-known/agent-skills/` and related files act as the discoverable surface for AI agents.

10. Content management appears to be supported by static admin tooling rather than a backend service. `public/admin/` contains a Decap CMS-style admin entrypoint and config, indicating content edits are likely authored through files in Git rather than stored in a database.

11. Static assets live in `public/`, including images, the CV PDF, and SEO/accessibility files like `robots.txt`. These are served directly by the Next.js/Netlify host and are part of the site’s public contract.

12. Operationally, the repo is kept lightweight: no backend API service, no database layer, and no separate worker process. The main architectural boundary is between file-based content, React presentation, and Netlify edge/deployment features.

Main entry points: [`src/app/page.tsx`](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/page.tsx) (Home page), [`src/app/layout.tsx`](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/layout.tsx) (App shell), [`src/app/blog/[slug]/page.tsx`](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/blog/[slug]/page.tsx) (Post page), [`public`](https://github.com/ahmed-abdelwahed1/personal-website/tree/main/public) (Public assets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Next.js app"]
  node_layout["App shell<br/>Next layout<br/>[layout.tsx]"]
  node_home["Home page<br/>Route page<br/>[page.tsx]"]
  node_blog_index["Blog index<br/>Route page<br/>[page.tsx]"]
  node_blog_post["Post page<br/>Dynamic route<br/>[page.tsx]"]
  node_sitemap["Sitemap<br/>Metadata route<br/>[sitemap.ts]"]
  node_content_lib["Content loader<br/>Content adapter<br/>[content.ts]"]
  node_blog_lib["Blog loader<br/>Markdown parser<br/>[blog.ts]"]
end

subgraph group_components["UI components"]
  node_theme["Theme<br/>Client provider<br/>[ThemeProvider.tsx]"]
  node_hero["Hero<br/>Section component<br/>[Hero.tsx]"]
  node_experience["Experience<br/>Section component"]
  node_projects["Projects<br/>Section component"]
  node_education["Education<br/>Section component"]
  node_badges["Badges<br/>Section component<br/>[BadgesSection.tsx]"]
  node_volunteering["Volunteering<br/>Section component"]
  node_heatmap["GitHub heatmap<br/>Section component"]
  node_blog_ui["Blog UI<br/>Article components"]
  node_seo["SEO metadata<br/>Structured data<br/>[JsonLd.tsx]"]
  node_analytics["Analytics<br/>Client tracker<br/>[Analytics.tsx]"]
end

subgraph group_content["File content"]
  node_site_content["Profile JSON<br/>Content data<br/>[hero.json]"]
  node_blog_content["Blog markdown<br/>Post content"]
end

subgraph group_public["Public surface"]
  node_public_surface[("Public assets<br/>Static assets")]
  node_well_known["Well-known<br/>Discovery files<br/>[.well-known]"]
  node_admin["Admin CMS<br/>Static CMS"]
end

subgraph group_deploy["Deploy edge"]
  node_edge_md["Markdown edge<br/>Netlify edge"]
  node_netlify_cfg["Netlify config<br/>Hosting config<br/>[netlify.toml]"]
end

node_layout -->|"provides"| node_theme
node_layout -->|"loads"| node_analytics
node_layout -->|"hosts"| node_home
node_layout -->|"hosts"| node_blog_index
node_layout -->|"hosts"| node_blog_post
node_home -->|"reads"| node_content_lib
node_home -->|"renders"| node_hero
node_home -->|"renders"| node_experience
node_home -->|"renders"| node_projects
node_home -->|"renders"| node_education
node_home -->|"renders"| node_badges
node_home -->|"renders"| node_volunteering
node_home -->|"renders"| node_heatmap
node_content_lib -->|"loads"| node_site_content
node_blog_index -->|"reads"| node_blog_lib
node_blog_post -->|"reads"| node_blog_lib
node_blog_post -->|"uses"| node_blog_ui
node_blog_index -->|"uses"| node_seo
node_blog_post -->|"uses"| node_seo
node_blog_post -->|"sources"| node_blog_content
node_sitemap -->|"indexes"| node_public_surface
node_public_surface -->|"contains"| node_well_known
node_public_surface -->|"contains"| node_admin
node_admin -.->|"edits via"| node_content_lib
node_edge_md -->|"negotiates"| node_blog_lib
node_netlify_cfg -->|"enables"| node_edge_md
node_netlify_cfg -->|"serves"| node_public_surface

click node_layout "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/layout.tsx"
click node_home "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/page.tsx"
click node_blog_index "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/blog/page.tsx"
click node_blog_post "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/blog/[slug]/page.tsx"
click node_sitemap "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/sitemap.ts"
click node_content_lib "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/lib/content.ts"
click node_blog_lib "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/lib/blog.ts"
click node_theme "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/ThemeProvider.tsx"
click node_hero "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/Hero.tsx"
click node_experience "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/ExperienceSection.tsx"
click node_projects "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/ProjectsSection.tsx"
click node_education "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/EducationSection.tsx"
click node_badges "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/BadgesSection.tsx"
click node_volunteering "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/VolunteeringSection.tsx"
click node_heatmap "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/GithubHeatmapSection.tsx"
click node_blog_ui "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/ReadingProgress.tsx"
click node_seo "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/JsonLd.tsx"
click node_analytics "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/Analytics.tsx"
click node_site_content "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/content/site/hero.json"
click node_blog_content "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/content/blog/building-etl-pipelines.md"
click node_public_surface "https://github.com/ahmed-abdelwahed1/personal-website/tree/main/public"
click node_well_known "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/public/.well-known"
click node_admin "https://github.com/ahmed-abdelwahed1/personal-website/tree/main/public/admin"
click node_edge_md "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/netlify/edge-functions/markdown-negotiation.ts"
click node_netlify_cfg "https://github.com/ahmed-abdelwahed1/personal-website/blob/main/netlify.toml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_layout,node_home,node_blog_index,node_blog_post,node_sitemap,node_content_lib,node_blog_lib toneBlue
class node_theme,node_hero,node_experience,node_projects,node_education,node_badges,node_volunteering,node_heatmap,node_blog_ui,node_seo,node_analytics toneAmber
class node_site_content,node_blog_content toneMint
class node_public_surface,node_well_known,node_admin toneRose
class node_edge_md,node_netlify_cfg toneIndigo
```

## Components

### Next.js app

App Router routes, shell, and site-level rendering.

- [App shell](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/layout.tsx): Next layout · Root document shell and global providers. · `src/app/layout.tsx`
- [Home page](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/page.tsx): Route page · Portfolio landing page composition. · `src/app/page.tsx`
- [Blog index](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/blog/page.tsx): Route page · Lists blog posts from local markdown content. · `src/app/blog/page.tsx`
- [Post page](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/blog/[slug]/page.tsx): Dynamic route · Renders an individual blog post by slug. · `src/app/blog/[slug]/page.tsx`
- [Sitemap](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/app/sitemap.ts): Metadata route · Generates sitemap output for crawlers. · `src/app/sitemap.ts`
- [Content loader](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/lib/content.ts): Content adapter · Main boundary from JSON content to homepage sections. · `src/lib/content.ts`
- [Blog loader](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/lib/blog.ts): Markdown parser · Reads and parses blog posts from content/blog. · `src/lib/blog.ts`

### UI components

Reusable presentation, SEO, and client-side behavior.

- [Theme](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/ThemeProvider.tsx): Client provider · Global theme state and toggle behavior. · `src/components/ThemeProvider.tsx`
- [Hero](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/Hero.tsx): Section component · Top-level profile introduction section. · `src/components/Hero.tsx`
- [Experience](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/ExperienceSection.tsx): Section component · Work history presentation section. · `src/components/ExperienceSection.tsx`
- [Projects](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/ProjectsSection.tsx): Section component · Project showcase section. · `src/components/ProjectsSection.tsx`
- [Education](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/EducationSection.tsx): Section component · Education section. · `src/components/EducationSection.tsx`
- [Badges](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/BadgesSection.tsx): Section component · Credential and badge section. · `src/components/BadgesSection.tsx`
- [Volunteering](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/VolunteeringSection.tsx): Section component · Volunteer work section. · `src/components/VolunteeringSection.tsx`
- [GitHub heatmap](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/GithubHeatmapSection.tsx): Section component · Activity visualization section. · `src/components/GithubHeatmapSection.tsx`
- [Blog UI](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/ReadingProgress.tsx): Article components · Reading progress, tracker, and blog-specific metadata. · `src/components/ReadingProgress.tsx`
- [SEO metadata](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/JsonLd.tsx): Structured data · JSON-LD helpers for site and blog pages. · `src/components/JsonLd.tsx`
- [Analytics](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/src/components/Analytics.tsx): Client tracker · Site and article tracking hooks. · `src/components/Analytics.tsx`

### File content

Static profile and blog sources consumed at build/runtime.

- [Profile JSON](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/content/site/hero.json): Content data · Structured homepage and profile content. · `content/site/hero.json`
- [Blog markdown](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/content/blog/building-etl-pipelines.md): Post content · Markdown blog posts used by the article pipeline. · `content/blog/building-etl-pipelines.md`

### Public surface

Static assets and machine-discoverable endpoints.

- [Public assets](https://github.com/ahmed-abdelwahed1/personal-website/tree/main/public): Static assets · Images, PDF CV, robots.txt, and admin entrypoint. · `public`
- [Well-known](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/public/.well-known): Discovery files · Agent, MCP, OAuth, and OpenID discovery metadata. · `public/.well-known`
- [Admin CMS](https://github.com/ahmed-abdelwahed1/personal-website/tree/main/public/admin): Static CMS · Decap-style browser editor for git-backed content. · `public/admin`

### Deploy edge

Netlify hosting and edge request handling.

- [Markdown edge](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/netlify/edge-functions/markdown-negotiation.ts): Netlify edge · Content negotiation for text/markdown responses. · `netlify/edge-functions/markdown-negotiation.ts`
- [Netlify config](https://github.com/ahmed-abdelwahed1/personal-website/blob/main/netlify.toml): Hosting config · Netlify deployment and runtime settings. · `netlify.toml`

## Connections

- App shell → Theme: provides · Wraps the app in global theme behavior.
- App shell → Analytics: loads · Registers global client behavior.
- App shell → Home page: hosts · Defines the app shell for the homepage.
- App shell → Blog index: hosts · Provides shared shell for blog routes.
- App shell → Post page: hosts · Provides shared shell for dynamic post pages.
- Home page → Content loader: reads · Pulls structured site content through the content boundary.
- Home page → Hero: renders · Assembles the homepage hero section.
- Home page → Experience: renders · Assembles the experience section.
- Home page → Projects: renders · Assembles the projects section.
- Home page → Education: renders · Assembles the education section.
- Home page → Badges: renders · Assembles the badges section.
- Home page → Volunteering: renders · Assembles the volunteering section.
- Home page → GitHub heatmap: renders · Assembles the activity visualization section.
- Content loader → Profile JSON: loads · Reads local JSON profile content.
- Blog index → Blog loader: reads · Fetches blog post metadata and summaries.
- Post page → Blog loader: reads · Loads and parses the requested markdown post.
- Post page → Blog UI: uses · Enhances article reading experience.
- Blog index → SEO metadata: uses · Adds structured data for discovery.
- Post page → SEO metadata: uses · Adds article structured data.
- Post page → Blog markdown: sources · Renders content from markdown files.
- Sitemap → Public assets: indexes · Exposes public site routes to crawlers.
- Public assets → Well-known: contains · Holds machine-discoverable metadata files.
- Public assets → Admin CMS: contains · Serves the static admin UI.
- Admin CMS → Content loader: edits via · Supports file-backed content authoring.
- Markdown edge → Blog loader: negotiates · Serves markdown representations for blog content.
- Netlify config → Markdown edge: enables · Registers the edge-function deployment path.
- Netlify config → Public assets: serves · Defines hosting behavior for static assets.
