URL Shortener

A full-stack sample application demonstrating URL shortening, built with .NET 10, Blazor Web App (server-side rendering), minimal APIs, and SQLite via EF Core.

Features

✅ Shorten URLs — Convert any HTTP/HTTPS URL to a 7-character short code
✅ Public redirects — Share /r/{code} links that redirect to the original URL
✅ Custom aliases — Reserve readable aliases when a generated code is not the right fit
✅ Expiration controls — Set or clear expiry windows during creation and later management
✅ Click tracking — Monitor how many times each link has been accessed
✅ Inventory management — View all your created links with metadata and statistics
✅ Analytics reporting — Review top links, quiet links, and expiration watch lists
✅ Admin-ready routing — Separate creation, management, analytics, and admin landing views
✅ Validation — URL format and length validation with clear error messages

Quick Start

Prerequisites

• .NET 10.0.x SDK — Download

Run Locally

# Restore dependencies
dotnet restore UrlShortener.slnx

# Build
dotnet build UrlShortener.slnx -c Release

# Start the application
dotnet run --project src/UrlShortener.Web/UrlShortener.Web.csproj

Open http://localhost:5000 in your browser.

Create a Shortened Link

1. Enter a long URL in the form on the home page
2. Click "Shorten"
3. Copy the short code (e.g., aBcDeFg)
4. Optionally choose a custom alias or expiration before saving
5. Share /r/aBcDeFg (or your alias) with others
6. View management controls at /links, reporting at /analytics, and the admin hand-off at /admin

Verify Tests Pass

dotnet test UrlShortener.slnx -c Release

Architecture

The application is organized as:

• Frontend: Blazor Web App with server-side rendering (creation, management, analytics, and admin views)
• Backend: Minimal APIs for creating, resolving, listing, and updating shortened links
• Database: SQLite with EF Core for persistence
• Validation: URL, alias, and expiration checks in the business logic layer
• Testing: Integration tests with isolated in-memory database per test

See Architecture for system design details.

Repository Layout

src/UrlShortener.Web/          Main application: Blazor pages + minimal APIs
tests/UrlShortener.Web.Tests/  Integration tests
docs/                           Documentation and phase blog
  ├── bugfixes/                 Numbered bug fix summaries
  ├── getting-started.md        Setup and first steps
  ├── architecture.md           System design and technical decisions
  ├── developer-guide.md        Contribution workflow and patterns
  └── blog/                     Numbered phase release posts
README.md                        This file

Documentation

• Getting Started — Local setup and basic workflows
• Architecture — System design, components, and decisions
• Developer Guide — Code organization, testing, extension points
• Bugfix Summaries — Numbered records of evidenced bug fixes and validation
• Phase Blog — Progress tracking and design rationale

Current Phase

✅ Phase 2 is complete — Full-stack application with Blazor UI and link management.

Features landed:

• Phase 0: Solution scaffold, minimal APIs skeleton
• Phase 1: Core URL shortening backend with click tracking
• Phase 2: Blazor SSR frontend with inventory and statistics

See Phase Blog for what was built in each phase and what's coming next.

API Endpoints

Quick reference (see Architecture for details):

# Create a shortened link
POST /api/links
  Input:  { "originalUrl": "https://example.com/long/url" }
  Output: { "shortCode": "aBcDeFg", "createdUtc": "...", ... }

# List all links
GET /api/links
  Output: [{ "shortCode": "aBcDeFg", ... }, ...]

# Redirect to original URL (also increments clicks)
GET /r/{shortCode}
  Response: 302 Found, Location: {original URL}

# Health check
GET /api/health
  Output: { "status": "Healthy", "serviceName": "UrlShortener", ... }

Testing

# Run all tests
dotnet test UrlShortener.slnx -c Release

# Run with verbose output
dotnet test UrlShortener.slnx -c Release --verbosity normal

Tests cover:

• Home page rendering
• Link creation via API
• URL redirect and click tracking
• Link listing and inventory
• Validation and error handling

Development

See Developer Guide for:

• Local development setup and hot reload
• Code organization and project structure
• Testing strategy and patterns
• How to add new features

Next Steps

New to the project?

1. Read Getting Started to set up locally
2. Read Architecture to understand the design
3. Check Phase Blog to see what's been built

Contributing?

1. Follow Developer Guide
2. Run tests before committing
3. Update documentation if your changes affect user or developer workflows

Evaluating Squad?

• See .squad/ for process artifacts (decisions, agent context)
• Review docs/blog/ for phase-based delivery approach
• Note the numbered blog posts as a requirement, not optional documentation

Project Status

Current: Phase 2 (Blazor UI + inventory) complete and tested.
Next: Phase 3 (authentication, custom aliases, analytics) and Phase 4 (final docs).

See Phase Blog for detailed status and planned features.