How ankit-gupta-git/portfolio-v1 works
1. Overall shape
This is a two-part portfolio application: a React/Vite frontend that renders the public site, plus a small Node.js backend dedicated to AI-assistant functionality. The frontend is the main product surface; the backend exists as a focused API layer rather than a broad application server.
2. Frontend as a single-page portfolio shell
The frontend is organized around a section-based SPA layout rather than a large route graph. App.jsx and components/Layout.jsx likely compose the page into major portfolio sections such as Hero, About, Skills, Projects, Experience, Blog, Contact, and supporting UI elements like Navbar and Footer.
3. Content and presentation are mostly component-driven
Most of the site appears to be rendered from static or semi-static React components under src/components. This includes portfolio sections, reusable project cards, and specialized UX pieces like the Terminal, Fluid Cursor, Loader, and ProblemSolving views. That makes the UI architecture highly modular and easy to rearrange without changing the underlying data flow much.
4. Shared UI infrastructure
A separate components/ui area contains cross-cutting widgets such as the AI assistant widget, back-to-top button, blob background, GitHub contributions visualizer, tech stack carousel, timeline, sparkles effect, and theme context. These are not business logic features; they are mostly presentation and interaction primitives reused across the portfolio.
5. Client-side state and interaction
Two custom hooks, useTheme.js and useFluidCursor.js, suggest the app has a small amount of global or shared client state for visual behavior. The theme system is important architecture-wise because it coordinates persistent light/dark mode behavior across the whole frontend, likely via context plus local preference storage.
6. Animated, experience-focused UI
The presence of Framer Motion, GSAP, and custom animated components means the frontend is built as an interaction-heavy showcase site, not a simple static brochure. Animations and motion effects are part of the architecture because they influence component boundaries and how sections mount, animate, and respond to scroll.
7. Assets and static content
The public/ directory contains the resume PDF, project images, icons, blog images, and custom fonts. These assets are treated as static delivery content and feed the visual sections directly. This means the app’s “data model” is mostly embedded assets plus component props, not a remote CMS.
8. Contact and external integrations
The README indicates the contact form is handled through Formspree, so contact submission is likely an external service integration from the frontend rather than an internal backend workflow. The GitHub contributions widget also implies a read-only integration with GitHub’s public activity data.
9. Backend is a narrow AI service
The backend has a classic layered structure: server.js bootstraps the app, src/app.js wires middleware and routes, controllers/ai.controller.js handles request/response logic, routes/ai.routes.js exposes the endpoint(s), and services/ai.services.js contains the AI-specific integration logic. This separation strongly suggests the backend is designed to isolate AI provider calls and keep the frontend from talking directly to that provider.
10. AI assistant data flow
The main backend data path is likely: frontend AI widget → backend AI route → controller → service → external AI API → response back to widget. That makes the backend a thin orchestration layer, probably also protecting API credentials through environment variables (backend/.env.sample).
11. Build and runtime boundaries
The frontend runs on React 19 + Vite and is deployed separately from the backend in a typical static-hosting setup. The backend is a Node.js API process with its own package manifest, which means the system is split along a clear boundary: static client delivery versus server-side AI request mediation.
12. Architecture summary for a diagram
If you draw this repository, the main boxes should be: Frontend SPA shell, portfolio content components, UI/animation utilities, external services (Formspree, GitHub/public data, AI provider), and a backend AI API acting only as a secure bridge for the assistant widget. The dominant flow is user interaction in the frontend, with one specialized server round-trip for AI responses.
Main entry points: ui UI primitives · Layout.jsx Layout · components Portfolio sections · app.js API app
Components 18
Frontend
React/Vite portfolio application and its UI composition
- App shell · Top-level portfolio page composition and section layout
frontend/src/App.jsx - Layout · Shared page framing around the section-based site
frontend/src/components/Layout.jsx - Portfolio sections · Hero, About, Skills, Projects, Experience, Blog, Contact, and related sections
frontend/src/components - Nav & footer · Navbar and footer that anchor the single-page experience
frontend/src/components/Navbar.jsx - Feature views · Specialized sections like Terminal, Loader, ProblemSolving, and other interactive portfolio views
frontend/src/components - Project cards · Reusable project and content card building blocks
frontend/src/components/ProjectCard.jsx - UI primitives · Cross-cutting widgets and effects used across the portfolio
frontend/src/components/ui - Theme context · Global light/dark theme coordination for the frontend
frontend/src/components/ui/ThemeContext.jsx - Client hooks · Shared interaction state such as theme and fluid cursor behavior
frontend/src/hooks - Static assets · Resume, fonts, icons, images, and blog/project media served directly
frontend/public
Backend
Node API dedicated to AI assistant requests
- Server entry · Starts the AI API process
backend/server.js - API app · Wires middleware and route mounting
backend/src/app.js - AI routes · Endpoint surface for assistant requests
backend/src/routes/ai.routes.js - AI controller · Validates and shapes AI request/response flow
backend/src/controllers/ai.controller.js - AI service · Calls the AI provider and encapsulates provider-specific behavior
backend/src/services/ai.services.js
External services
Third-party services and static delivery inputs
- Formspree · Handles contact form submission from the frontend
- GitHub data · Public repository/activity data for contributions display
- AI provider · Upstream model or assistant service used by the backend
Connections 19
- App shell → Layout: uses · App composes the shared page shell
- Layout → Nav & footer: contains · Layout includes navigation and footer chrome
- Layout → Portfolio sections: frames · Layout arranges the main portfolio sections
- Portfolio sections → Feature views: includes · Section content can embed showcase views
- Portfolio sections → Project cards: renders · Project and content sections reuse card components
- App shell → UI primitives: uses · App-wide widgets and effects support the UI
- UI primitives → Theme context: provides · Theme context is a central shared UI concern
- Client hooks → Theme context: supports · Hooks participate in global UI state behavior
- Client hooks → UI primitives: drives · Cursor and interaction hooks feed shared effects
- UI primitives → AI provider: calls · Assistant widget communicates with the backend AI service path
- UI primitives → Formspree: submits to · Contact UI sends form data to Formspree
- UI primitives → GitHub data: reads · Contributions widget displays public GitHub activity data
- UI primitives → Static assets: uses · Widgets and sections consume static media and fonts
- Server entry → API app: boots · Server entry initializes the Express app
- API app → AI routes: mounts · App exposes the AI route set
- AI routes → AI controller: delegates · Routes hand requests to controller logic
- AI controller → AI service: uses · Controller calls the AI integration layer
- AI service → AI provider: invokes · Service reaches the external AI provider
- API app → UI primitives: serves assistant traffic · Backend exists primarily to support the frontend assistant widget