How shaheeii/shaheem-portfolio works
Project type & purpose (from file tree + README)
This is a Next.js (App Router) TypeScript application, likely an AI Studio “Gemini” demo/app. The README focuses on running locally and requires GEMINI_API_KEY, which strongly implies:
• The UI is served by Next.js pages/components under app/.
• Server-side functionality exists via Route Handlers under app/api/**/route.ts.
• The app integrates with Google Gemini API (external service) using the API key in .env.local.
This is not a separate “frontend + backend repo”; it’s a single Next.js full-stack app (React UI + server routes in one codebase).
Key directories/files and what they represent architecturally:
Server / Backend (inside Next.js)
• app/api/contact/route.ts – server endpoint for contact form submission (likely POST)
• app/api/webhook/route.ts – server endpoint to receive external callbacks (webhooks)
Shared utilities / platform glue
• lib/utils.ts – shared helper functions (formatting, validation, fetch wrappers, etc.)
• hooks/use-mobile.ts – client hook (responsive behavior)
• next.config.ts, tsconfig.json, ESLint configs – build/runtime configuration
Environment / Secrets
• .env.example – documents needed env vars
• README: .env.local + GEMINI_API_KEY – secret used by server route handlers to call Gemini
Next.js Application (Node.js runtime)
• App Router UI (React server/client components: app/*, components/*)
• API Route Handlers (app/api/contact, app/api/webhook)
External Services
• Google Gemini API (called using GEMINI_API_KEY)
Architectural pattern to highlight
• “Full-stack Next.js App Router”: UI and server endpoints live together.
• API routes as the boundary for secrets: GEMINI_API_KEY should only be used server-side in app/api/**.
• Componentized UI: The UI is broken into section components (Hero, Portfolio, Philosophy, Contact, etc.).
• No explicit database layer shown: Important to reflect that the architecture is currently stateless *unless the API routes persist somewhere (not visible in the tree).*
Concrete labeling: what to name nodes (map to files)
Use labels that tie directly back to the repo to keep it “accurate”:
UI
• app/page.tsx (Home Page)
• app/layout.tsx (Root Layout)
• components/Contact.tsx (Contact Form UI)
• components/Hero.tsx, components/Navbar.tsx, etc. (Landing sections)
• hooks/use-mobile.ts (Responsive Hook)
Backend
• app/api/contact/route.ts (Contact API)
• app/api/webhook/route.ts (Webhook API)
• lib/utils.ts (Shared Utilities)
External
• Google Gemini API
• External Webhook Provider (unknown)
Diagramming conventions to make it “best and most accurate”
Elements explicitly:
Clear labels
• route paths on API nodes:
• POST /api/contact
• POST /api/webhook
• runtime boundary labels: “Browser”, “Next.js (Server)”, “External”.
• HTTPS GET (HTML/JS/CSS) Browser → Next.js
• HTTPS POST (form JSON) Browser → /api/contact
• HTTPS POST (event JSON) Webhook Provider → /api/webhook
• HTTPS POST (prompt/messages) Next.js API → Gemini
• HTTPS response (completion JSON) Gemini → Next.js API
Trust boundaries (important here)
• Public Internet (Browser + External webhook provider)
• Your Server (Next.js runtime)
That:
• GEMINI_API_KEY stays inside server boundary (never in browser)
Deliver these artifacts:
That combination will be both detailed and faithful to this repo’s structure, while making the Gemini integration and Next.js full-stack nature immediately clear.