# piyush-eon/url-shortener architecture

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

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

## Overview

1. **Overall shape**
   - This is a **client-side React SPA** for a URL shortener/analytics app.
   - The frontend is built with **Vite**, styled with **Tailwind CSS**, and composed using **shadcn/ui** primitives.
   - There is **no custom backend in this repo**; the app talks to **Supabase** for auth and data storage.

2. **Main runtime boundary**
   - `src/main.jsx` boots the app and mounts the root React tree.
   - `src/App.jsx` is the top-level composition point for layout and routing.
   - `src/layouts/app-layout.jsx` and `src/components/header.jsx` form the persistent shell around pages.

3. **Routing and page boundaries**
   - The application is organized into page-level screens under `src/pages/`:
     - `landing.jsx` for the marketing/entry experience
     - `auth.jsx` for sign-in/sign-up flows
     - `dashboard.jsx` for the authenticated workspace
     - `link.jsx` for viewing/managing a specific short link
     - `redirect-link.jsx` for public short-link resolution and redirect behavior
   - `src/components/require-auth.jsx` acts as a route guard for protected areas.

4. **Authentication subsystem**
   - Auth is handled through Supabase via `src/db/apiAuth.js` and `src/db/supabase.js`.
   - `src/components/login.jsx` and `src/components/signup.jsx` provide the user-facing forms.
   - `src/context.jsx` likely stores the current auth/session state and exposes it to the rest of the app.
   - The key boundary is: **UI triggers auth actions → Supabase manages identity/session → context updates app state**.

5. **URL management subsystem**
   - Short-link creation is centered in `src/components/create-link.jsx`.
   - Persistence and lookup go through `src/db/apiUrls.js`.
   - `src/components/link-card.jsx` is the reusable presentation unit for a stored short link in lists and dashboards.
   - The data flow is: **user submits long URL → API layer stores/creates short code in Supabase → dashboard renders the saved link**.

6. **Redirect and click-tracking flow**
   - `src/pages/redirect-link.jsx` is the public-facing entry point for a short URL.
   - It likely resolves the slug, records the click, and then redirects the browser to the destination URL.
   - Click events are handled through `src/db/apiClicks.js`, which separates analytics writes from URL lookup.
   - This is an important architectural boundary: **resolution and tracking are split from the dashboard UI so public traffic can be recorded independently of authenticated management**.

7. **Analytics and reporting**
   - `src/components/device-stats.jsx` and `src/components/location-stats.jsx` represent aggregated click analytics.
   - These components probably consume click records from Supabase and summarize them by device type and geographic location.
   - Dashboard analytics are therefore a read-heavy layer built on top of click event data, not a separate service.

8. **Shared UI and composition**
   - `src/components/ui/` contains the reusable shadcn-style building blocks: buttons, cards, dialogs, inputs, tabs, dropdowns, avatars, accordion.
   - `src/components/error.jsx` provides a common failure state.
   - These components are used across auth, dashboard, and link-management screens to keep the app visually consistent without introducing business logic into the UI layer.

9. **Data access layer**
   - `src/db/` is the main abstraction boundary between React and Supabase:
     - `supabase.js` creates/configures the client
     - `apiAuth.js` handles auth operations
     - `apiUrls.js` handles URL CRUD and lookup
     - `apiClicks.js` handles click inserts and analytics reads
   - This separation keeps pages/components free from direct database concerns and makes Supabase the only external persistence dependency.

10. **Cross-cutting state and async handling**
   - `src/hooks/use-fetch.js` is a reusable async-data helper, likely used to standardize loading/error handling.
   - `src/context.jsx` likely coordinates global app state such as the current user, session, or theme-related app concerns.
   - `src/lib/utils.js` contains shared utilities used by the UI layer.

11. **Deployment and hosting assumptions**
   - The presence of `.htaccess` suggests the app is intended for **static hosting with SPA fallback routing**, so direct navigation to routes like `/dashboard` or `/link/:id` still resolves correctly.
   - `public/` contains static assets, while `index.html` is the SPA entry.
   - `vite.config.js`, `tailwind.config.js`, `postcss.config.js`, and `components.json` indicate a standard Vite/Tailwind/shadcn toolchain.

12. **Diagram-level takeaway**
   - The architecture is best drawn as:
     - **Browser UI shell**
     - **Authenticated dashboard and public redirect routes**
     - **Shared component library**
     - **Local data-access layer**
     - **Supabase backend for auth, URL records, and click analytics**
   - The most important flows are:
     - sign up / log in
     - create short URL
     - resolve short URL
     - record click analytics
     - display dashboard/reporting for the authenticated owner

Main entry points: [`src/App.jsx`](https://github.com/piyush-eon/url-shortener/blob/master/src/App.jsx) (App), [`src/pages/dashboard.jsx`](https://github.com/piyush-eon/url-shortener/blob/master/src/pages/dashboard.jsx) (Dashboard), [`src/db/apiUrls.js`](https://github.com/piyush-eon/url-shortener/blob/master/src/db/apiUrls.js) (URL API), [`src/db/apiClicks.js`](https://github.com/piyush-eon/url-shortener/blob/master/src/db/apiClicks.js) (Clicks API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_runtime["App runtime"]
  node_src_main["main<br/>SPA entry<br/>[main.jsx]"]
  node_src_app["App<br/>root shell<br/>[App.jsx]"]
  node_src_layout["App layout<br/>layout shell<br/>[app-layout.jsx]"]
  node_src_header["Header<br/>nav shell<br/>[header.jsx]"]
  node_page_landing["Landing<br/>marketing page<br/>[landing.jsx]"]
  node_page_auth["Auth<br/>[auth.jsx]"]
  node_page_dashboard["Dashboard<br/>workspace page<br/>[dashboard.jsx]"]
  node_page_link["Link page<br/>link detail page<br/>[link.jsx]"]
  node_page_redirect["Redirect<br/>public resolver<br/>[redirect-link.jsx]"]
end

subgraph group_group_features["Feature screens"]
  node_guard_auth["Require auth<br/>route guard<br/>[require-auth.jsx]"]
  node_cmp_login["Login<br/>auth form<br/>[login.jsx]"]
  node_cmp_signup["Signup<br/>auth form<br/>[signup.jsx]"]
  node_cmp_create_link["Create link<br/>link form<br/>[create-link.jsx]"]
  node_cmp_link_card["Link card<br/>link summary<br/>[link-card.jsx]"]
  node_cmp_device_stats["Device stats<br/>analytics view<br/>[device-stats.jsx]"]
  node_cmp_location_stats["Location stats<br/>analytics view<br/>[location-stats.jsx]"]
end

subgraph group_group_data["Data access"]
  node_db_supabase["Supabase client<br/>backend client<br/>[supabase.js]"]
  node_db_auth["Auth API<br/>auth data API<br/>[apiAuth.js]"]
  node_db_urls["URL API<br/>url data API<br/>[apiUrls.js]"]
  node_db_clicks["Clicks API<br/>analytics data API<br/>[apiClicks.js]"]
end

subgraph group_group_shared["Shared UI"]
  node_ctx_app["Context<br/>global state<br/>[context.jsx]"]
  node_hook_fetch["useFetch<br/>async helper<br/>[use-fetch.js]"]
  node_lib_utils["Utils<br/>shared helpers<br/>[utils.js]"]
end

node_src_main -->|"mounts"| node_src_app
node_src_app -->|"wraps"| node_src_layout
node_src_layout -->|"contains"| node_src_header
node_src_app -->|"routes to"| node_page_landing
node_src_app -->|"routes to"| node_page_auth
node_src_app -->|"routes to"| node_page_dashboard
node_src_app -->|"routes to"| node_page_link
node_src_app -->|"routes to"| node_page_redirect
node_page_dashboard -->|"protected by"| node_guard_auth
node_page_link -->|"protected by"| node_guard_auth
node_page_auth -->|"uses"| node_cmp_login
node_page_auth -->|"uses"| node_cmp_signup
node_page_dashboard -->|"uses"| node_cmp_create_link
node_page_dashboard -->|"lists"| node_cmp_link_card
node_page_dashboard -->|"shows"| node_cmp_device_stats
node_page_dashboard -->|"shows"| node_cmp_location_stats
node_cmp_login -->|"calls"| node_db_auth
node_cmp_signup -->|"calls"| node_db_auth
node_cmp_create_link -->|"calls"| node_db_urls
node_page_link -->|"loads"| node_db_urls
node_page_redirect -->|"resolves"| node_db_urls
node_page_redirect -->|"records"| node_db_clicks
node_cmp_device_stats -->|"queries"| node_db_clicks
node_cmp_location_stats -->|"queries"| node_db_clicks
node_db_auth -->|"uses"| node_db_supabase
node_db_urls -->|"uses"| node_db_supabase
node_db_clicks -->|"uses"| node_db_supabase
node_src_app -->|"shares"| node_ctx_app
node_page_auth -->|"updates"| node_ctx_app
node_hook_fetch -.->|"supports"| node_db_urls
node_hook_fetch -.->|"supports"| node_db_clicks
node_src_header -.->|"uses"| node_lib_utils

click node_src_main "https://github.com/piyush-eon/url-shortener/blob/master/src/main.jsx"
click node_src_app "https://github.com/piyush-eon/url-shortener/blob/master/src/App.jsx"
click node_src_layout "https://github.com/piyush-eon/url-shortener/blob/master/src/layouts/app-layout.jsx"
click node_src_header "https://github.com/piyush-eon/url-shortener/blob/master/src/components/header.jsx"
click node_page_landing "https://github.com/piyush-eon/url-shortener/blob/master/src/pages/landing.jsx"
click node_page_auth "https://github.com/piyush-eon/url-shortener/blob/master/src/pages/auth.jsx"
click node_page_dashboard "https://github.com/piyush-eon/url-shortener/blob/master/src/pages/dashboard.jsx"
click node_page_link "https://github.com/piyush-eon/url-shortener/blob/master/src/pages/link.jsx"
click node_page_redirect "https://github.com/piyush-eon/url-shortener/blob/master/src/pages/redirect-link.jsx"
click node_guard_auth "https://github.com/piyush-eon/url-shortener/blob/master/src/components/require-auth.jsx"
click node_cmp_login "https://github.com/piyush-eon/url-shortener/blob/master/src/components/login.jsx"
click node_cmp_signup "https://github.com/piyush-eon/url-shortener/blob/master/src/components/signup.jsx"
click node_cmp_create_link "https://github.com/piyush-eon/url-shortener/blob/master/src/components/create-link.jsx"
click node_cmp_link_card "https://github.com/piyush-eon/url-shortener/blob/master/src/components/link-card.jsx"
click node_cmp_device_stats "https://github.com/piyush-eon/url-shortener/blob/master/src/components/device-stats.jsx"
click node_cmp_location_stats "https://github.com/piyush-eon/url-shortener/blob/master/src/components/location-stats.jsx"
click node_db_supabase "https://github.com/piyush-eon/url-shortener/blob/master/src/db/supabase.js"
click node_db_auth "https://github.com/piyush-eon/url-shortener/blob/master/src/db/apiAuth.js"
click node_db_urls "https://github.com/piyush-eon/url-shortener/blob/master/src/db/apiUrls.js"
click node_db_clicks "https://github.com/piyush-eon/url-shortener/blob/master/src/db/apiClicks.js"
click node_ctx_app "https://github.com/piyush-eon/url-shortener/blob/master/src/context.jsx"
click node_hook_fetch "https://github.com/piyush-eon/url-shortener/blob/master/src/hooks/use-fetch.js"
click node_lib_utils "https://github.com/piyush-eon/url-shortener/blob/master/src/lib/utils.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_src_main,node_src_app,node_src_layout,node_src_header,node_page_landing,node_page_auth,node_page_dashboard,node_page_link,node_page_redirect toneBlue
class node_guard_auth,node_cmp_login,node_cmp_signup,node_cmp_create_link,node_cmp_link_card,node_cmp_device_stats,node_cmp_location_stats toneAmber
class node_db_supabase,node_db_auth,node_db_urls,node_db_clicks toneMint
class node_ctx_app,node_hook_fetch,node_lib_utils toneRose
```

## Components

### App runtime

React SPA bootstrap, routing, layouts, and page boundaries.

- [main](https://github.com/piyush-eon/url-shortener/blob/master/src/main.jsx): SPA entry · Bootstraps React and mounts the app. · `src/main.jsx`
- [App](https://github.com/piyush-eon/url-shortener/blob/master/src/App.jsx): root shell · Top-level composition and routing. · `src/App.jsx`
- [App layout](https://github.com/piyush-eon/url-shortener/blob/master/src/layouts/app-layout.jsx): layout shell · Persistent application frame around pages. · `src/layouts/app-layout.jsx`
- [Header](https://github.com/piyush-eon/url-shortener/blob/master/src/components/header.jsx): nav shell · Top-level navigation and account controls. · `src/components/header.jsx`
- [Landing](https://github.com/piyush-eon/url-shortener/blob/master/src/pages/landing.jsx): marketing page · Public entry and marketing experience. · `src/pages/landing.jsx`
- [Auth](https://github.com/piyush-eon/url-shortener/blob/master/src/pages/auth.jsx): auth page · Sign-in and sign-up screen boundary. · `src/pages/auth.jsx`
- [Dashboard](https://github.com/piyush-eon/url-shortener/blob/master/src/pages/dashboard.jsx): workspace page · Authenticated dashboard and reporting view. · `src/pages/dashboard.jsx`
- [Link page](https://github.com/piyush-eon/url-shortener/blob/master/src/pages/link.jsx): link detail page · View and manage a specific short link. · `src/pages/link.jsx`
- [Redirect](https://github.com/piyush-eon/url-shortener/blob/master/src/pages/redirect-link.jsx): public resolver · Resolves a short link and redirects visitors. · `src/pages/redirect-link.jsx`

### Feature screens

User-facing pages and feature components for auth, links, and analytics.

- [Require auth](https://github.com/piyush-eon/url-shortener/blob/master/src/components/require-auth.jsx): route guard · Protects authenticated routes. · `src/components/require-auth.jsx`
- [Login](https://github.com/piyush-eon/url-shortener/blob/master/src/components/login.jsx): auth form · Sign-in form and submission flow. · `src/components/login.jsx`
- [Signup](https://github.com/piyush-eon/url-shortener/blob/master/src/components/signup.jsx): auth form · Account creation form and submission flow. · `src/components/signup.jsx`
- [Create link](https://github.com/piyush-eon/url-shortener/blob/master/src/components/create-link.jsx): link form · Creates new short URLs from long URLs. · `src/components/create-link.jsx`
- [Link card](https://github.com/piyush-eon/url-shortener/blob/master/src/components/link-card.jsx): link summary · Reusable card for stored short links. · `src/components/link-card.jsx`
- [Device stats](https://github.com/piyush-eon/url-shortener/blob/master/src/components/device-stats.jsx): analytics view · Aggregates clicks by device type. · `src/components/device-stats.jsx`
- [Location stats](https://github.com/piyush-eon/url-shortener/blob/master/src/components/location-stats.jsx): analytics view · Aggregates clicks by geographic location. · `src/components/location-stats.jsx`

### Data access

Supabase client and repository-specific API wrappers.

- [Supabase client](https://github.com/piyush-eon/url-shortener/blob/master/src/db/supabase.js): backend client · Configured Supabase connection for auth and storage. · `src/db/supabase.js`
- [Auth API](https://github.com/piyush-eon/url-shortener/blob/master/src/db/apiAuth.js): auth data API · Authentication and session operations. · `src/db/apiAuth.js`
- [URL API](https://github.com/piyush-eon/url-shortener/blob/master/src/db/apiUrls.js): url data API · Short-link lookup, creation, and persistence. · `src/db/apiUrls.js`
- [Clicks API](https://github.com/piyush-eon/url-shortener/blob/master/src/db/apiClicks.js): analytics data API · Click inserts and reporting queries. · `src/db/apiClicks.js`

### Shared UI

Reusable cross-cutting components and helpers.

- [Context](https://github.com/piyush-eon/url-shortener/blob/master/src/context.jsx): global state · App-wide session and shared state. · `src/context.jsx`
- [useFetch](https://github.com/piyush-eon/url-shortener/blob/master/src/hooks/use-fetch.js): async helper · Reusable async loading and error handling. · `src/hooks/use-fetch.js`
- [Utils](https://github.com/piyush-eon/url-shortener/blob/master/src/lib/utils.js): shared helpers · Common utility functions used across UI. · `src/lib/utils.js`

## Connections

- main → App: mounts · React entry mounts the root app.
- App → App layout: wraps · App composes the persistent shell.
- App layout → Header: contains · Layout includes the shared header.
- App → Landing: routes to · Public entry route.
- App → Auth: routes to · Authentication route.
- App → Dashboard: routes to · Authenticated workspace route.
- App → Link page: routes to · Short-link detail route.
- App → Redirect: routes to · Public redirect route.
- Dashboard → Require auth: protected by · Dashboard requires authentication.
- Link page → Require auth: protected by · Link management requires authentication.
- Auth → Login: uses · Auth page renders login form.
- Auth → Signup: uses · Auth page renders signup form.
- Dashboard → Create link: uses · Dashboard provides link creation.
- Dashboard → Link card: lists · Dashboard shows stored links.
- Dashboard → Device stats: shows · Dashboard includes device analytics.
- Dashboard → Location stats: shows · Dashboard includes location analytics.
- Login → Auth API: calls · Login submits auth operations.
- Signup → Auth API: calls · Signup submits auth operations.
- Create link → URL API: calls · Creates and stores short links.
- Link page → URL API: loads · Fetches link details for editing or viewing.
- Redirect → URL API: resolves · Looks up destination URL by slug.
- Redirect → Clicks API: records · Tracks public click events before redirecting.
- Device stats → Clicks API: queries · Reads click data for device breakdowns.
- Location stats → Clicks API: queries · Reads click data for location breakdowns.
- Auth API → Supabase client: uses · Auth API delegates to Supabase client.
- URL API → Supabase client: uses · URL API delegates to Supabase client.
- Clicks API → Supabase client: uses · Clicks API delegates to Supabase client.
- App → Context: shares · App consumes global session/state context.
- Auth → Context: updates · Auth flow updates session state.
- useFetch → URL API: supports · Async helper can standardize data loading.
- useFetch → Clicks API: supports · Async helper can standardize analytics loading.
- Header → Utils: uses · Header and UI share common helpers.
