# manojgaddigolla/url-shortener architecture

> Architecture diagram of the GitHub repository manojgaddigolla/url-shortener, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/manojgaddigolla/url-shortener
- Repository: https://github.com/manojgaddigolla/url-shortener

## Overview

Short.ly is a full-stack URL shortener: visitors create links anonymously or while signed in, then short codes redirect to destinations while recording click telemetry. Signed-in users manage links and inspect analytics; optional AI features suggest aliases and answer questions about traffic. The graph follows the visible Express routing and controller calls and the documented client capabilities. Some client and route implementations were not excerpted, so those connections are omitted where evidence is limited.

Main entry points: [`backend/server.js`](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/server.js) (Express server), [`client/src/App.jsx`](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/App.jsx) (React application), [`client/src/services/linkService.js`](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/services/linkService.js) (Link API client), [`client/src/pages/ShortenPage.jsx`](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/pages/ShortenPage.jsx) (Shorten page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web client"]
  node_webapp["React application<br/>[App.jsx]"]
  node_home["Home page<br/>[HomePage.jsx]"]
  node_shortenui["Shorten page<br/>[ShortenPage.jsx]"]
  node_dashboard["Dashboard<br/>[DashboardPage.jsx]"]
  node_analyticsmodal["Analytics modal"]
  node_navbar["Navigation<br/>[Navbar.jsx]"]
  node_linkclient["Link API client<br/>[linkService.js]"]
  node_apiclient["API client<br/>[apiService.js]"]
  node_authclient["Auth service<br/>[authService.js]"]
end

subgraph group_api["HTTP API"]
  node_server["Express server<br/>[server.js]"]
  node_urlroutes["Short URL routes<br/>[urls.js]"]
  node_linkroutes["Link routes<br/>[links.js]"]
  node_redirect_routes["Redirect routes<br/>[index.js]"]
  node_webhookroutes["Webhook route<br/>[webhooks.js]"]
  node_urlcontroller["URL controller<br/>[urlController.js]"]
  node_linkscontroller["Link controller<br/>[linksController.js]"]
  node_webhookcontroller["Webhook controller"]
  node_errors["Error middleware<br/>[errorMiddleware.js]"]
end

subgraph group_identity["Identity and persistence"]
  node_urlmodel[("URL records<br/>[Url.js]")]
  node_usermodel[("User records<br/>[User.js]")]
  node_database[("MongoDB")]
  node_dbconnector["Database connection<br/>[db.js]"]
end

subgraph group_integrations["External services"]
  node_clerk["Clerk identity"]
  node_gemini["Gemini AI"]
end

node_visitor(("Visitor"))

node_visitor -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_home
node_webapp -->|"routes to"| node_shortenui
node_webapp -->|"protects route"| node_dashboard
node_webapp -->|"renders"| node_navbar
node_shortenui -->|"calls"| node_linkclient
node_shortenui -->|"calls"| node_apiclient
node_dashboard -->|"calls"| node_linkclient
node_dashboard -->|"renders"| node_analyticsmodal
node_analyticsmodal -->|"calls"| node_linkclient
node_linkclient -->|"HTTP requests"| node_server
node_server -->|"mounts"| node_urlroutes
node_server -->|"mounts"| node_linkroutes
node_server -->|"mounts"| node_redirect_routes
node_server -->|"mounts"| node_webhookroutes
node_urlroutes -->|"dispatches"| node_urlcontroller
node_redirect_routes -->|"dispatches"| node_urlcontroller
node_linkroutes -->|"dispatches"| node_linkscontroller
node_webhookroutes -->|"dispatches"| node_webhookcontroller
node_urlcontroller -->|"reads and writes"| node_urlmodel
node_linkscontroller -->|"reads and writes"| node_urlmodel
node_webhookcontroller -->|"upserts and deletes"| node_usermodel
node_server -->|"connects"| node_dbconnector
node_dbconnector -->|"connects to"| node_database
node_urlmodel -.->|"persists"| node_database
node_usermodel -.->|"persists"| node_database
node_linkscontroller -->|"requests insights"| node_gemini
node_webhookcontroller -->|"verifies events"| node_clerk
node_server -->|"handles errors"| node_errors

click node_webapp "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/App.jsx"
click node_home "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/pages/HomePage.jsx"
click node_shortenui "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/pages/ShortenPage.jsx"
click node_dashboard "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/pages/DashboardPage.jsx"
click node_analyticsmodal "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/components/LinkAnalyticsModal.jsx"
click node_navbar "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/components/Navbar.jsx"
click node_linkclient "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/services/linkService.js"
click node_apiclient "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/services/apiService.js"
click node_authclient "https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/services/authService.js"
click node_server "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/server.js"
click node_urlroutes "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/routes/urls.js"
click node_linkroutes "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/routes/links.js"
click node_redirect_routes "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/routes/index.js"
click node_webhookroutes "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/routes/webhooks.js"
click node_urlcontroller "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/controllers/urlController.js"
click node_linkscontroller "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/controllers/linksController.js"
click node_webhookcontroller "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/controllers/webhookController.js"
click node_errors "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/middleware/errorMiddleware.js"
click node_urlmodel "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/models/Url.js"
click node_usermodel "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/models/User.js"
click node_dbconnector "https://github.com/manojgaddigolla/url-shortener/blob/main/backend/config/db.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_webapp,node_home,node_shortenui,node_dashboard,node_analyticsmodal,node_navbar,node_linkclient,node_apiclient,node_authclient toneBlue
class node_server,node_urlroutes,node_linkroutes,node_redirect_routes,node_webhookroutes,node_urlcontroller,node_linkscontroller,node_webhookcontroller,node_errors toneAmber
class node_urlmodel,node_usermodel,node_database,node_dbconnector toneMint
class node_clerk,node_gemini toneRose
class node_visitor toneIndigo
```

## Components

### Web client

- [React application](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Home page](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/pages/HomePage.jsx): `client/src/pages/HomePage.jsx`
- [Shorten page](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/pages/ShortenPage.jsx): `client/src/pages/ShortenPage.jsx`
- [Dashboard](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/pages/DashboardPage.jsx): `client/src/pages/DashboardPage.jsx`
- [Analytics modal](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/components/LinkAnalyticsModal.jsx): `client/src/components/LinkAnalyticsModal.jsx`
- [Navigation](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/components/Navbar.jsx): `client/src/components/Navbar.jsx`
- [Link API client](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/services/linkService.js): `client/src/services/linkService.js`
- [API client](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/services/apiService.js): `client/src/services/apiService.js`
- [Auth service](https://github.com/manojgaddigolla/url-shortener/blob/main/client/src/services/authService.js): `client/src/services/authService.js`

### HTTP API

- [Express server](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/server.js): `backend/server.js`
- [Short URL routes](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/routes/urls.js): `backend/routes/urls.js`
- [Link routes](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/routes/links.js): `backend/routes/links.js`
- [Redirect routes](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/routes/index.js): `backend/routes/index.js`
- [Webhook route](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/routes/webhooks.js): `backend/routes/webhooks.js`
- [URL controller](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/controllers/urlController.js): `backend/controllers/urlController.js`
- [Link controller](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/controllers/linksController.js): `backend/controllers/linksController.js`
- [Webhook controller](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/controllers/webhookController.js): `backend/controllers/webhookController.js`
- [Error middleware](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/middleware/errorMiddleware.js): `backend/middleware/errorMiddleware.js`

### Identity and persistence

- [URL records](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/models/Url.js): `backend/models/Url.js`
- [User records](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/models/User.js): `backend/models/User.js`
- **MongoDB**
- [Database connection](https://github.com/manojgaddigolla/url-shortener/blob/main/backend/config/db.js): `backend/config/db.js`

### External services

- **Clerk identity**
- **Gemini AI**

### Other components

- **Visitor**

## Connections

- Visitor → React application: uses (evidence: `README.md`)
- React application → Home page: routes to (evidence: `client/src/App.jsx`)
- React application → Shorten page: routes to (evidence: `client/src/App.jsx`)
- React application → Dashboard: protects route (evidence: `client/src/App.jsx`)
- React application → Navigation: renders (evidence: `client/src/App.jsx`)
- Shorten page → Link API client: calls (evidence: `client/src/pages/ShortenPage.jsx`)
- Shorten page → API client: calls (evidence: `client/src/pages/ShortenPage.jsx`)
- Dashboard → Link API client: calls (evidence: `client/src/pages/DashboardPage.jsx`)
- Dashboard → Analytics modal: renders (evidence: `client/src/pages/DashboardPage.jsx`)
- Analytics modal → Link API client: calls (evidence: `client/src/components/LinkAnalyticsModal.jsx`)
- Link API client → Express server: HTTP requests (evidence: `client/src/services/linkService.js`)
- Express server → Short URL routes: mounts (evidence: `backend/server.js`)
- Express server → Link routes: mounts (evidence: `backend/server.js`)
- Express server → Redirect routes: mounts (evidence: `backend/server.js`)
- Express server → Webhook route: mounts (evidence: `backend/server.js`)
- Short URL routes → URL controller: dispatches (evidence: `backend/routes/urls.js`)
- Redirect routes → URL controller: dispatches (evidence: `backend/routes/index.js`)
- Link routes → Link controller: dispatches (evidence: `backend/routes/links.js`)
- Webhook route → Webhook controller: dispatches (evidence: `backend/routes/webhooks.js`)
- URL controller → URL records: reads and writes (evidence: `backend/controllers/urlController.js`)
- Link controller → URL records: reads and writes (evidence: `backend/controllers/linksController.js`)
- Webhook controller → User records: upserts and deletes (evidence: `backend/controllers/webhookController.js`)
- Express server → Database connection: connects (evidence: `backend/server.js`)
- Database connection → MongoDB: connects to (evidence: `backend/config/db.js`)
- URL records → MongoDB: persists (evidence: `README.md`)
- User records → MongoDB: persists (evidence: `README.md`)
- Link controller → Gemini AI: requests insights (evidence: `backend/controllers/linksController.js`)
- Webhook controller → Clerk identity: verifies events (evidence: `backend/controllers/webhookController.js`)
- Express server → Error middleware: handles errors (evidence: `backend/server.js`)
