How ahmed-abdelwahed1/personal-website works
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: app/page.tsx Home page · layout.tsx App shell · [slug]/page.tsx Post page · public Public assets
Components 25
Next.js app
App Router routes, shell, and site-level rendering.
- App shell · Root document shell and global providers.
src/app/layout.tsx - Home page · Portfolio landing page composition.
src/app/page.tsx - Blog index · Lists blog posts from local markdown content.
src/app/blog/page.tsx - Post page · Renders an individual blog post by slug.
src/app/blog/[slug]/page.tsx - Sitemap · Generates sitemap output for crawlers.
src/app/sitemap.ts - Content loader · Main boundary from JSON content to homepage sections.
src/lib/content.ts - Blog loader · Reads and parses blog posts from content/blog.
src/lib/blog.ts
UI components
Reusable presentation, SEO, and client-side behavior.
- Theme · Global theme state and toggle behavior.
src/components/ThemeProvider.tsx - Hero · Top-level profile introduction section.
src/components/Hero.tsx - Experience · Work history presentation section.
src/components/ExperienceSection.tsx - Projects · Project showcase section.
src/components/ProjectsSection.tsx - Education · Education section.
src/components/EducationSection.tsx - Badges · Credential and badge section.
src/components/BadgesSection.tsx - Volunteering · Volunteer work section.
src/components/VolunteeringSection.tsx - GitHub heatmap · Activity visualization section.
src/components/GithubHeatmapSection.tsx - Blog UI · Reading progress, tracker, and blog-specific metadata.
src/components/ReadingProgress.tsx - SEO metadata · JSON-LD helpers for site and blog pages.
src/components/JsonLd.tsx - Analytics · Site and article tracking hooks.
src/components/Analytics.tsx
File content
Static profile and blog sources consumed at build/runtime.
- Profile JSON · Structured homepage and profile content.
content/site/hero.json - Blog markdown · Markdown blog posts used by the article pipeline.
content/blog/building-etl-pipelines.md
Public surface
Static assets and machine-discoverable endpoints.
- Public assets · Images, PDF CV, robots.txt, and admin entrypoint.
public - Well-known · Agent, MCP, OAuth, and OpenID discovery metadata.
public/.well-known - Admin CMS · Decap-style browser editor for git-backed content.
public/admin
Deploy edge
Netlify hosting and edge request handling.
- Markdown edge · Content negotiation for text/markdown responses.
netlify/edge-functions/markdown-negotiation.ts - Netlify config · Netlify deployment and runtime settings.
netlify.toml
Connections 27
- 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.