How piyush-eon/url-shortener works
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: App.jsx App · dashboard.jsx Dashboard · apiUrls.js URL API · apiClicks.js Clicks API
Components 23
App runtime
React SPA bootstrap, routing, layouts, and page boundaries.
- main · Bootstraps React and mounts the app.
src/main.jsx - App · Top-level composition and routing.
src/App.jsx - App layout · Persistent application frame around pages.
src/layouts/app-layout.jsx - Header · Top-level navigation and account controls.
src/components/header.jsx - Landing · Public entry and marketing experience.
src/pages/landing.jsx - Auth · Sign-in and sign-up screen boundary.
src/pages/auth.jsx - Dashboard · Authenticated dashboard and reporting view.
src/pages/dashboard.jsx - Link page · View and manage a specific short link.
src/pages/link.jsx - Redirect · 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 · Protects authenticated routes.
src/components/require-auth.jsx - Login · Sign-in form and submission flow.
src/components/login.jsx - Signup · Account creation form and submission flow.
src/components/signup.jsx - Create link · Creates new short URLs from long URLs.
src/components/create-link.jsx - Link card · Reusable card for stored short links.
src/components/link-card.jsx - Device stats · Aggregates clicks by device type.
src/components/device-stats.jsx - Location stats · Aggregates clicks by geographic location.
src/components/location-stats.jsx
Data access
Supabase client and repository-specific API wrappers.
- Supabase client · Configured Supabase connection for auth and storage.
src/db/supabase.js - Auth API · Authentication and session operations.
src/db/apiAuth.js - URL API · Short-link lookup, creation, and persistence.
src/db/apiUrls.js - Clicks API · Click inserts and reporting queries.
src/db/apiClicks.js
Connections 32
- 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.