# ankit-gupta-git/portfolio-v1 architecture

> Architecture diagram of the GitHub repository ankit-gupta-git/portfolio-v1, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ankit-gupta-git/portfolio-v1
- Repository: https://github.com/ankit-gupta-git/portfolio-v1

## Overview

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: [`frontend/src/components/ui`](https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/components/ui) (UI primitives), [`frontend/src/components/Layout.jsx`](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/Layout.jsx) (Layout), [`frontend/src/components`](https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/components) (Portfolio sections), [`backend/src/app.js`](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/app.js) (API app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_frontend_app["App shell<br/>React SPA<br/>[App.jsx]"]
  node_frontend_layout["Layout<br/>page frame<br/>[Layout.jsx]"]
  node_frontend_sections["Portfolio sections<br/>content sections"]
  node_frontend_nav_ui["Nav & footer<br/>site chrome<br/>[Navbar.jsx]"]
  node_frontend_feature_views["Feature views<br/>showcase components"]
  node_frontend_cards["Project cards<br/>presentation components<br/>[ProjectCard.jsx]"]
  node_frontend_ui["UI primitives<br/>shared widgets"]
  node_frontend_theme["Theme context<br/>ui state<br/>[ThemeContext.jsx]"]
  node_frontend_hooks["Client hooks<br/>custom hooks"]
  node_frontend_assets[("Static assets<br/>public content")]
end

subgraph group_backend["Backend"]
  node_backend_server["Server entry<br/>Node bootstrap<br/>[server.js]"]
  node_backend_app["API app<br/>Express app<br/>[app.js]"]
  node_backend_routes["AI routes<br/>HTTP routes<br/>[ai.routes.js]"]
  node_backend_controller["AI controller<br/>request handler<br/>[ai.controller.js]"]
  node_backend_service["AI service<br/>integration logic<br/>[ai.services.js]"]
end

subgraph group_external["External services"]
  node_service_formspree["Formspree<br/>external form service"]
  node_service_github["GitHub data<br/>external data source"]
  node_service_ai["AI provider<br/>external API"]
end

node_frontend_app -->|"uses"| node_frontend_layout
node_frontend_layout -->|"contains"| node_frontend_nav_ui
node_frontend_layout -->|"frames"| node_frontend_sections
node_frontend_sections -->|"includes"| node_frontend_feature_views
node_frontend_sections -->|"renders"| node_frontend_cards
node_frontend_app -->|"uses"| node_frontend_ui
node_frontend_ui -->|"provides"| node_frontend_theme
node_frontend_hooks -->|"supports"| node_frontend_theme
node_frontend_hooks -->|"drives"| node_frontend_ui
node_frontend_ui -->|"calls"| node_service_ai
node_frontend_ui -->|"submits to"| node_service_formspree
node_frontend_ui -->|"reads"| node_service_github
node_frontend_ui -->|"uses"| node_frontend_assets
node_backend_server -->|"boots"| node_backend_app
node_backend_app -->|"mounts"| node_backend_routes
node_backend_routes -->|"delegates"| node_backend_controller
node_backend_controller -->|"uses"| node_backend_service
node_backend_service -->|"invokes"| node_service_ai
node_backend_app -.->|"serves assistant traffic"| node_frontend_ui

click node_frontend_app "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/App.jsx"
click node_frontend_layout "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/Layout.jsx"
click node_frontend_sections "https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/components"
click node_frontend_nav_ui "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/Navbar.jsx"
click node_frontend_feature_views "https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/components"
click node_frontend_cards "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/ProjectCard.jsx"
click node_frontend_ui "https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/components/ui"
click node_frontend_theme "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/ui/ThemeContext.jsx"
click node_frontend_hooks "https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/hooks"
click node_frontend_assets "https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/public"
click node_backend_server "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/server.js"
click node_backend_app "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/app.js"
click node_backend_routes "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/routes/ai.routes.js"
click node_backend_controller "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/controllers/ai.controller.js"
click node_backend_service "https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/services/ai.services.js"

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_frontend_app,node_frontend_layout,node_frontend_sections,node_frontend_nav_ui,node_frontend_feature_views,node_frontend_cards,node_frontend_ui,node_frontend_theme,node_frontend_hooks,node_frontend_assets toneBlue
class node_backend_server,node_backend_app,node_backend_routes,node_backend_controller,node_backend_service toneAmber
class node_service_formspree,node_service_github,node_service_ai toneMint
```

## Components

### Frontend

React/Vite portfolio application and its UI composition

- [App shell](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/App.jsx): React SPA · Top-level portfolio page composition and section layout · `frontend/src/App.jsx`
- [Layout](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/Layout.jsx): page frame · Shared page framing around the section-based site · `frontend/src/components/Layout.jsx`
- [Portfolio sections](https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/components): content sections · Hero, About, Skills, Projects, Experience, Blog, Contact, and related sections · `frontend/src/components`
- [Nav & footer](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/Navbar.jsx): site chrome · Navbar and footer that anchor the single-page experience · `frontend/src/components/Navbar.jsx`
- [Feature views](https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/components): showcase components · Specialized sections like Terminal, Loader, ProblemSolving, and other interactive portfolio views · `frontend/src/components`
- [Project cards](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/ProjectCard.jsx): presentation components · Reusable project and content card building blocks · `frontend/src/components/ProjectCard.jsx`
- [UI primitives](https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/components/ui): shared widgets · Cross-cutting widgets and effects used across the portfolio · `frontend/src/components/ui`
- [Theme context](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/frontend/src/components/ui/ThemeContext.jsx): ui state · Global light/dark theme coordination for the frontend · `frontend/src/components/ui/ThemeContext.jsx`
- [Client hooks](https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/src/hooks): custom hooks · Shared interaction state such as theme and fluid cursor behavior · `frontend/src/hooks`
- [Static assets](https://github.com/ankit-gupta-git/portfolio-v1/tree/main/frontend/public): public content · Resume, fonts, icons, images, and blog/project media served directly · `frontend/public`

### Backend

Node API dedicated to AI assistant requests

- [Server entry](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/server.js): Node bootstrap · Starts the AI API process · `backend/server.js`
- [API app](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/app.js): Express app · Wires middleware and route mounting · `backend/src/app.js`
- [AI routes](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/routes/ai.routes.js): HTTP routes · Endpoint surface for assistant requests · `backend/src/routes/ai.routes.js`
- [AI controller](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/controllers/ai.controller.js): request handler · Validates and shapes AI request/response flow · `backend/src/controllers/ai.controller.js`
- [AI service](https://github.com/ankit-gupta-git/portfolio-v1/blob/main/backend/src/services/ai.services.js): integration logic · 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**: external form service · Handles contact form submission from the frontend
- **GitHub data**: external data source · Public repository/activity data for contributions display
- **AI provider**: external API · Upstream model or assistant service used by the backend

## Connections

- 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
