Urlvy transforms long, ugly URLs into memorable slugs, enriches them with AI-powered summaries and tracks every click in real-time. Share, analyse, and chat with an AI analyst about your traffic – all in one slick workspace.
Think “Bitly × Mixpanel” with a built-in data scientist. 🚀
Important
Born from my frustration with blind, un-branded links. Urlvy gives marketers, dev-rels and indie hackers immediate feedback on every share.
- About Urlvy
- Live Demo
- Feature Highlights
- Tech Stack & Architecture
- Architecture Diagram
- Screenshots
- Database Schema
- Getting Started
- API Reference
- Deployment Guide
- Scripts & Makefile
- Nhost Backup Backend
- Testing
- CI/CD
- Docker & Compose
- AWS Deployment
- Contributing
- License
- Author
Urlvy is a full-stack URL platform that lets you:
- 🔐 Shorten & brand links with custom slugs
- 💬 AI summaries – fetches the titles & generates AI-powered two-line previews automatically
- 📈 Live analytics – track clicks, referrers, devices, geos in real-time and more
- 🤖 Chat with UrlvyStatsBot – ask “Why did clicks spike yesterday?” and get insights
- ⏲ TTL & auto-expire – set links to self-destruct or pause whenever
- 📊 Dashboard – global stats across every link, top performers & histograms
- 🛡 Security first – JWT, RBAC guards, rate-limited endpoints
- 🧰 REST + Swagger – fully typed OpenAPI 3.1 spec, ready for your automation
Built for growth hackers, product teams and indie makers who need answers, not raw CSVs.
Urlvy is live and ready to use! Check it out:
- Frontend – https://urlvy.vercel.app
- Backend API - Swagger Docs – https://api.urlvy.app/docs
Feel free to register with a throw-away address and play – no credit card, no limits during beta.
Caution
The demo may be down periodically due to inactivity or maintenance. If you encounter issues, please try again later or deploy your own instance using the instructions below. Please don't rely on the demo for production use, as it may not always be available!
Urlvy packs a punch with its features, designed to make link management and analytics a breeze:
| Category | Goodies |
|---|---|
| Link Ops | One-click shorten, custom slug, edit destination, expire × date or by clicks |
| Analytics | 30-day line chart, hourly bar, weekday bar, device pie, interval histogram & scatter |
| AI | Summaries on create, conversational stats bot with full chat history |
| Auth | Register, login, JWT refresh, forgot-password (email verify + reset) |
| UI/UX | Dark mode, skeleton loaders, animated counters, responsive & accessible |
| Docs | Swagger UI served 100 % from CDN, favicon, OpenAPI JSON at /docs-json |
| DevX | ESLint, Prettier, Husky, Type-safe DTOs, Zod on FE, ValidationPipe on BE |
| Ops | Docker-Compose dev stack, Postgres 15, Redis cache (future), GitHub Actions CI, AWS |
We use a very modern stack to ensure performance, scalability and developer experience!
| Layer | Stack |
|---|---|
| Frontend | Next.js 15 (App Router), React 18, TypeScript, Tailwind CSS, shadcn/ui, Recharts |
| Backend | NestJS 10, TypeORM, PostgreSQL, Swagger, class-validator |
| Auth | bcrypt, JWT RS256, Passport, CORS |
| AI | Google GenerativeAI Large Language Model (LLM) |
| Infra | Vercel / Docker-Compose local / Amazon Web Services |
| Dev Tools | Yarn Berry, ESLint, Prettier, Commitlint, Husky, GitHub Actions |
Here's a high-level overview of Urlvy's architecture (not necessarily complete, but gives you an idea of how the components interact):
flowchart TD
subgraph ClientApp[Client]
A[Next.js PWA]
end
subgraph CDNLayer[CDN]
CDN[Edge + Cache]
end
subgraph APILayer[API]
G[AWS<br/>NestJS API]
end
subgraph Database[DB]
P[(PostgreSQL ← TypeORM)]
end
subgraph AIService[AI]
M[Google AI LLM]
end
A -- Static assets --> CDN
A -- REST/JWT --> G
G -- SQL --> P
G -- Summaries / Chat --> M
style ClientApp fill:#d0e8ff,stroke:#333
style CDNLayer fill:#d0ffd8,stroke:#333
style APILayer fill:#ffd0d8,stroke:#333
style Database fill:#e0e0e0,stroke:#333
style AIService fill:#dcd0ff,stroke:#333
As mentioned, Urlvy uses PostgreSQL 15 with TypeORM for ORM. The schema is designed for performance and scalability, with UUIDs for primary keys and indexed foreign keys.
| Table | Fields (excerpt) | Notes |
|---|---|---|
| user | id UUID PK · email uniq · password_hash · created_at | salted Bcrypt 10 |
| url | id UUID · slug uniq · destination · summary · owner_id FK | summary pre-generated |
| click | id UUID · url_id FK · ip · user_agent · created_at | heavy SELECT indexing |
Full DDL in database/schema.sql.
git clone https://github.com/hoangsonww/Urlvy-URL-Shortener-App.git
cd Urlvy-URL-Shortener-App
# ─── Backend ─────────────────────────────────────────────
cd api
cp .env.example .env # fill PG_URL, JWT_SECRET, GOOGLE_API_KEY
docker compose up -d postgres
npm i && npm run dev # http://localhost:5001
# ─── Frontend ────────────────────────────────────────────
cd ../web
cp .env.local.example .env.local # NEXT_PUBLIC_API=...
npm i --legacy-peer-deps
npm run dev # http://localhost:3000Postgres' default URI:
postgres://urlvy:password@localhost:5432/urlvy_db. Change as needed.
We provide a fully typed REST API with OpenAPI 3.1 spec, accessible via Swagger UI. You have 2 options to explore the API documentation:
- Swagger UI:
/docs - JSON:
/docs-json
| Method | Endpoint | Description |
|---|---|---|
| POST | /auth/register |
create user → JWT |
| POST | /auth/login |
email + pwd → JWT |
| POST | /auth/forgot |
verify email exists |
| POST | /auth/reset |
reset pwd with token |
| GET | /urls |
list my URLs |
| POST | /urls |
create ({ destination, customSlug? }) |
| GET | /urls/:slug/details |
metadata + clicks (JSON) |
| GET | /urls/:slug |
302 redirect (HTML) |
| PATCH | /urls/:slug |
update destination |
| DELETE | /urls/:slug |
delete link |
| GET | /stats/:slug/daily |
array of { day,count } |
| POST | /urls/:slug/chat |
AI chat on stats |
| GET | /stats/global |
aggregated stats for all links |
Headers: Authorization: Bearer <token>
To deploy Urlvy, you have several options depending on your stack and preferences. Here are the recommended methods:
| Target | Steps |
|---|---|
| Vercel (web) | vercel --prod (auto from web/vercel.json) |
| Render (api) | Connect repo → pick api dir → build npm run build |
| AWS (api) | scripts/deploy.sh aws (requires AWS CLI) |
| Docker all-in-one | docker compose -f compose.prod.yml up --build -d |
| Railway | 1-click template in deploy/railway.json |
Required env vars: PORT, DATABASE_URL, JWT_SECRET, GOOGLE_API_KEY. Make sure to set them in your hosting provider's dashboard.
Urlvy uses a Makefile for common tasks to simplify development. Here are some key commands:
make setup-dev # Setup dev environment (api + web)
make start-dev # Start dev server (api + web)
make stop-dev # Stop dev server
# and many more deployment, testing, linting tasks. Please check the Makefile for full list,
# or:
make help # Show all available commandsIn addition to the Makefile, we have some shell scripts for convenience:
scripts/deploy.sh– deploy to AWS, Render, or Vercel (your choice)scripts/setup.sh– setup dev environment (Postgres, Redis, etc.)
Please ensure you have the necessary permissions and environment variables set before running these scripts. Also, visit these scripts to change/add any deployment configurations as needed before running.
Urlvy also provides a backup backend using Nhost, which is a serverless backend-as-a-service (BaaS) platform. This allows you to quickly set up a backend without managing servers.
To use the Nhost backend, follow these steps:
-
Create a Nhost Project:
- Go to Nhost and create a new project.
- Set up the database and authentication as per your requirements.
-
Configure Environment Variables:
- Update your
.envfile with the Nhost project details:NHOST_BACKEND_URL=https://<your-nhost-backend-url> NHOST_GRAPHQL_URL=https://<your-nhost-graphql-url>
- Update your
-
Install Nhost CLI:
- Install the Nhost CLI globally:
npm install -g nhost
- Install the Nhost CLI globally:
-
Run Nhost Locally (optional):
- If you want to run Nhost locally, you can use Docker:
docker run -d -p 1337:1337 -p 3000:3000 nhost/nhost
- This will start the Nhost backend on
http://localhost:1337.
- If you want to run Nhost locally, you can use Docker:
-
Start the Application:
- Run the application as usual:
cd ../web npm run dev
- Run the application as usual:
Note
Make sure to update the frontend code to use the Nhost backend URLs for API calls or it will default to the local API!
Urlvy has a comprehensive test suite to ensure reliability and quality:
- Backend Tests:
cd api
npm run test- Frontend Tests:
cd web
npm run testRunning tests will execute both unit and integration tests, ensuring all components work as expected.
Urlvy uses GitHub Actions for continuous integration and deployment. The CI/CD pipeline includes:
- Linting – runs ESLint and Prettier to ensure code quality
- Testing – executes unit and integration tests for both frontend and backend
- Build – compiles the Next.js app and NestJS API
- Deployment – deploys the frontend to Vercel and backend to AWS or Docker
- Notifications – sends notifications on success/failure to the PR or commit
- Cache – caches dependencies to speed up builds
- and more...
The CI/CD configuration is defined in .github/workflows/workflow.yml. You can customize it to fit your workflow.
Urlvy provides a Docker setup for both development and production environments. This allows you to run the application in isolated containers, making it easy to manage dependencies and configurations.
We have two main Docker Compose files:
compose.dev.yml– for local development (includes web, api, and pg)compose.prod.yml– for production deployment (includes web, api, pg, and Nginx)
To run, use:
docker compose up # dev: web + api + pg
docker compose -f compose.prod.yml up --build # prodIt will start the following services:
urlvy-backend– NestJSurlvy-frontend– Next.js static export (served by Nginx)urlvy-pg– Postgres 15 w/ init script
The production setup also includes an Nginx reverse proxy to serve the frontend and API securely.
For Kubernetes users, we provide a kubernetes/ directory with example manifests to deploy Urlvy on a Kubernetes cluster. This includes:
- Deployment manifests for the frontend and backend
- Service definitions for exposing the applications
- Ingress configuration for routing traffic
- PersistentVolumeClaims for PostgreSQL data storage
- and more...
Feel free to adapt these manifests to your cluster's requirements. You can use tools like kubectl or Helm to deploy Urlvy on Kubernetes.
Urlvy can be deployed on AWS using CloudFormation templates. The aws/ directory contains the necessary YAML files to set up the infrastructure:
ecs-backend.yml– deploys the NestJS API on ECSrds-postgresql.yml– provisions a PostgreSQL database on RDSs3-cloudfront.yml– sets up S3 for static assets and CloudFront for CDNdeploy.sh– a script to deploy all stacks in the correct order
For more details on deploying Urlvy on AWS, please refer to the AWS Deployment Guide.
We welcome contributions to Urlvy! If you have ideas, bug fixes or improvements, please follow these steps:
- Fork the repository
- Create a new branch:
git checkout -b feature/my-feature - Make your changes/improvements.
- Before committing, run
npm run lintandnpm run formatto ensure everything is in order. Add tests if applicable. - Commit your changes:
git commit -m "Add my feature" - Push to your fork:
git push origin feature/my-feature - Open a Pull Request against the
mainbranch of this repository. - Wait for review and address any feedback.
- Once approved, your changes will be merged!
Bug reports & feature requests are also welcomed via Issues. Feel free to open an issue if you find a bug or have a suggestion for a new feature.
MIT License © 2025 Son Nguyen.
You can use Urlvy in your projects, commercial or non-commercial, as long as you include the original license and attribution. You must attribute the original author in your project documentation or README, regardless of whether you modify the code or not, and what you use it for.
Made with ☕ and keyboard rage by Son Nguyen 😅. Feel free to reach out to me on the following platforms:
Alternatively, you can also open an issue on this repository if you have any questions or suggestions, or just drop a message in the Discussion tab.
Note
“Build links that talk back.” – The Urlvy tagline