URL Shortener — from 0 to big-tech scale

// build.gradle — this file tells Gradle (the build tool) what libraries to download
// and how to package the app. Spring Boot reads which libraries are on the classpath
// and AUTO-CONFIGURES beans for them (this is the magic called 'auto-configuration').
plugins {
    id 'java'
    // The Spring Boot plugin lets us run `./gradlew bootRun` and build a single runnable jar.
    id 'org.springframework.boot' version '3.3.2'
    // Manages dependency VERSIONS so we don't have to pin each one by hand.
    id 'io.spring.dependency-management' version '1.1.6'
}

group = 'com.example'
version = '0.0.1'

java {
    // Spring Boot 3 requires Java 17 or newer.
    sourceCompatibility = '17'
}

repositories {
    // Where Gradle downloads libraries from.
    mavenCentral()
}

dependencies {
    // 'web' brings in Spring MVC + an embedded Tomcat server, so the app serves HTTP.
    implementation 'org.springframework.boot:spring-boot-starter-web'
    // 'data-jpa' brings in JPA + Hibernate, so we map Java objects to DB rows.
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    // 'validation' enables @Valid / @NotBlank checks on incoming request bodies.
    implementation 'org.springframework.boot:spring-boot-starter-validation'
    // Flyway runs versioned SQL migrations on startup so the DB schema is reproducible.
    implementation 'org.flywaydb:flyway-core'
    implementation 'org.flywaydb:flyway-database-postgresql'
    // The Postgres JDBC driver — the code that actually talks to a Postgres database.
    runtimeOnly 'org.postgresql:postgresql'
    // Test libraries (JUnit + Spring test support).
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
}

tasks.named('test') {
    useJUnitPlatform()
}

# application.yml — Spring reads this on startup to configure beans.
# YAML uses indentation to nest settings.
spring:
  datasource:
    # The JDBC URL of the Postgres database the app connects to.
    url: jdbc:postgresql://localhost:5432/urlshortener
    username: postgres
    password: postgres
  jpa:
    hibernate:
      # 'validate' means: on startup, CHECK that the Java entities match the DB tables,
      # but DO NOT create or alter tables. Flyway owns the schema, not Hibernate.
      # (The dangerous alternative, 'update', lets Hibernate silently change prod tables.)
      ddl-auto: validate
    properties:
      hibernate:
        # Log the SQL Hibernate generates, nicely formatted — great for learning.
        format_sql: true
    # Print the SQL statements to the console so you can see what JPA actually runs.
    show-sql: true
  flyway:
    # Turn Flyway ON: it runs the versioned SQL files in db/migration before the app starts.
    enabled: true

# The base of the short URL we hand back to clients, e.g. http://localhost:8080/aB3xQ
app:
  base-url: http://localhost:8080

-- Flyway runs this file ONCE and records that it ran, in a table called flyway_schema_history.
-- The filename format is strict: V<version>__<description>.sql  (two underscores).
-- 'V1' is the version; running it twice is prevented by Flyway's checksum tracking.

CREATE TABLE short_url (
    -- BIGSERIAL = a 64-bit auto-incrementing integer backed by a Postgres SEQUENCE.
    -- This sequence is exactly the 'DB-sequence id' the Stage-0 IdGenerator reads.
    id          BIGSERIAL    PRIMARY KEY,

    -- The public short key, e.g. 'aB3xQ'. UNIQUE so two URLs can never share a key.
    short_key   VARCHAR(16)  NOT NULL UNIQUE,

    -- The original long URL we redirect to. TEXT has no length limit.
    long_url    TEXT         NOT NULL,

    -- When the row was created. NOT NULL so every row is auditable.
    created_at  TIMESTAMPTZ  NOT NULL DEFAULT now(),

    -- Optional expiry; NULL means 'never expires'.
    expires_at  TIMESTAMPTZ,

    -- Optional owner identifier (e.g. an API key or user id). NULL allowed in Stage 0.
    owner       VARCHAR(64)
);

-- An index on short_key so the redirect lookup (WHERE short_key = ?) is fast.
-- (UNIQUE already creates an index, but naming it makes intent explicit for the reader.)
CREATE INDEX idx_short_url_short_key ON short_url (short_key);

package com.example.urlshortener;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

// @SpringBootApplication is THREE annotations in one:
//   @Configuration      — this class can define beans
//   @EnableAutoConfiguration — wire beans automatically based on what's on the classpath
//   @ComponentScan      — find @Component/@Service/@RestController in this package and below
@SpringBootApplication
public class UrlShortenerApplication {

    // The normal Java entry point. SpringApplication.run() boots everything:
    // it starts the embedded Tomcat server, creates the bean container, runs Flyway,
    // and connects to Postgres. After this line the app is live and serving HTTP.
    public static void main(String[] args) {
        SpringApplication.run(UrlShortenerApplication.class, args);
    }
}

package com.example.urlshortener;

import jakarta.persistence.Column;
import jakarta.persistence.Entity;
import jakarta.persistence.GeneratedValue;
import jakarta.persistence.GenerationType;
import jakarta.persistence.Id;
import jakarta.persistence.Table;
import java.time.Instant;

// @Entity tells JPA/Hibernate: this class maps to a database table.
// @Table names the exact table (otherwise it guesses from the class name).
@Entity
@Table(name = "short_url")
public class ShortUrl {

    // @Id marks the primary-key field.
    // @GeneratedValue(IDENTITY) means: let the DATABASE generate the id (the BIGSERIAL
    // sequence) on INSERT, then read it back. This IS the Stage-0 DB-sequence strategy.
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    // Maps to the short_key column; unique + not null mirror the SQL migration.
    @Column(name = "short_key", nullable = false, unique = true, length = 16)
    private String shortKey;

    @Column(name = "long_url", nullable = false)
    private String longUrl;

    @Column(name = "created_at", nullable = false)
    private Instant createdAt;

    @Column(name = "expires_at")
    private Instant expiresAt;

    @Column(name = "owner")
    private String owner;

    // JPA REQUIRES a no-argument constructor to build the object when reading from the DB.
    protected ShortUrl() {
    }

    // A convenience constructor for our own code to create new rows.
    public ShortUrl(String longUrl, Instant expiresAt, String owner) {
        this.longUrl = longUrl;
        this.expiresAt = expiresAt;
        this.owner = owner;
        this.createdAt = Instant.now();
        // Note: id and shortKey are filled in AFTER insert (id by the DB, shortKey by the service).
    }

    // Standard getters/setters — JPA and Jackson (JSON) read fields through these.
    public Long getId() { return id; }
    public String getShortKey() { return shortKey; }
    public void setShortKey(String shortKey) { this.shortKey = shortKey; }
    public String getLongUrl() { return longUrl; }
    public Instant getCreatedAt() { return createdAt; }
    public Instant getExpiresAt() { return expiresAt; }
    public String getOwner() { return owner; }
}

package com.example.urlshortener;

import org.springframework.data.repository.CrudRepository;
import java.util.Optional;

// This is an INTERFACE with no body — and we never implement it ourselves.
// Spring Data JPA reads the interface at startup and GENERATES a working bean:
// save(), findById(), delete(), etc. all just work.
//
// CrudRepository<ShortUrl, Long> means: this repository stores ShortUrl entities
// whose primary key (id) type is Long.
public interface UrlRepository extends CrudRepository<ShortUrl, Long> {

    // A DERIVED QUERY METHOD. Spring Data parses the METHOD NAME 'findByShortKey'
    // and writes the SQL for us: SELECT * FROM short_url WHERE short_key = ?
    // Returning Optional makes 'not found' explicit instead of a null surprise.
    Optional<ShortUrl> findByShortKey(String shortKey);
}

package com.example.urlshortener;

// An interface with a single method. This is a deliberate SEAM.
// Today its only implementation is DbSequenceIdGenerator (a Postgres sequence).
// In Stage 3 we add SnowflakeIdGenerator — and because UrlService depends on THIS
// interface, not the concrete class, we swap the bean and change zero call sites.
//
// Rule of thumb honored here: introduce an interface the moment a real second
// implementation is coming and the spine depends on the seam — not one stage too early.
public interface IdGenerator {

    // Return the next numeric id. In Stage 0 it comes from the DB sequence;
    // in Stage 3 it comes from a Snowflake algorithm. Callers don't care which.
    long nextId();
}

package com.example.urlshortener;

// A pure utility class: no Spring annotations, no state, just math.
// Base62 uses digits + lowercase + uppercase = 62 characters, so a number becomes
// a short, URL-safe string. id 125 -> '21', a big id -> 'aZ9k', etc.
public final class Base62Encoder {

    // The 62 symbols. The index of a character is its 'digit value' in base 62.
    private static final String ALPHABET =
            "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
    private static final int BASE = ALPHABET.length(); // 62

    // private constructor: this class is never instantiated, only its static methods are used.
    private Base62Encoder() {
    }

    // Encode a non-negative number into a base62 string.
    public static String encode(long value) {
        // 0 is a special case: the loop below would produce an empty string for it.
        if (value == 0) {
            return String.valueOf(ALPHABET.charAt(0));
        }
        StringBuilder sb = new StringBuilder();
        // Repeatedly take the remainder mod 62 to get the next digit, then divide.
        while (value > 0) {
            int remainder = (int) (value % BASE);
            sb.append(ALPHABET.charAt(remainder));
            value /= BASE;
        }
        // Digits came out least-significant first, so reverse to read normally.
        return sb.reverse().toString();
    }
}

package com.example.urlshortener;

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;

// @Component marks this class so Spring creates and manages ONE instance of it — a bean.
// Because it implements IdGenerator, Spring will inject it anywhere an IdGenerator is needed.
@Component
public class DbSequenceIdGenerator implements IdGenerator {

    // JdbcTemplate is Spring's thin helper for running raw SQL without boilerplate
    // (no manual Connection/Statement/try-finally). Spring auto-configures one for us.
    private final JdbcTemplate jdbcTemplate;

    // CONSTRUCTOR INJECTION: Spring sees this constructor needs a JdbcTemplate and
    // passes the bean in automatically. No @Autowired needed for a single constructor.
    public DbSequenceIdGenerator(JdbcTemplate jdbcTemplate) {
        this.jdbcTemplate = jdbcTemplate;
    }

    // @Override = we are implementing the IdGenerator.nextId() method.
    @Override
    public long nextId() {
        // Ask Postgres for the next value of the sequence that backs short_url.id.
        // BIGSERIAL secretly creates a sequence named '<table>_<column>_seq'.
        // queryForObject runs the SQL and returns exactly one value, cast to Long.
        Long next = jdbcTemplate.queryForObject(
                "SELECT nextval('short_url_id_seq')", Long.class);
        return next;
    }
}

package com.example.urlshortener;

import jakarta.validation.constraints.NotBlank;

// A DTO (Data Transfer Object): a plain object that mirrors the JSON the client sends.
// We keep it separate from the ShortUrl entity so the public API and the DB can evolve
// independently. A Java 'record' is a compact, immutable data carrier.
public record ShortenRequest(
        // @NotBlank rejects null/empty/whitespace-only longUrl with a 400 (via @Valid).
        @NotBlank String longUrl,
        // Optional fields — may be null. Wired up fully in later stages.
        String customAlias,
        Long ttlSeconds
) {
}

package com.example.urlshortener;

import java.time.Instant;

// The shape of the JSON we return from POST /api/urls.
// Again a record: immutable, and Jackson serializes its fields to JSON automatically.
public record ShortenResponse(
        String shortUrl,   // full clickable URL, e.g. http://localhost:8080/aB3xQ
        String shortKey,   // just the key, e.g. aB3xQ
        Instant expiresAt  // when it expires, or null if never
) {
}

package com.example.urlshortener;

// A custom unchecked exception (extends RuntimeException, so no 'throws' clause needed).
// We throw this when a short key isn't found; the GlobalExceptionHandler turns it into 404.
public class NotFoundException extends RuntimeException {
    public NotFoundException(String message) {
        super(message);
    }
}

package com.example.urlshortener;

import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import java.time.Instant;

// @Service marks this as a bean holding business logic. Functionally it's like @Component,
// but it documents intent: this is the service layer between the controller and the data.
@Service
public class UrlService {

    // Two collaborators, both injected. UrlService depends on the IdGenerator INTERFACE,
    // not on DbSequenceIdGenerator — that's the seam that lets Stage 3 swap in Snowflake.
    private final UrlRepository repository;
    private final IdGenerator idGenerator;

    // Constructor injection: Spring passes in the repository bean and the IdGenerator bean.
    public UrlService(UrlRepository repository, IdGenerator idGenerator) {
        this.repository = repository;
        this.idGenerator = idGenerator;
    }

    // @Transactional: run this whole method in ONE database transaction. If anything throws,
    // the INSERT is rolled back so we never leave a half-written row.
    @Transactional
    public ShortUrl shorten(String longUrl, Instant expiresAt, String owner) {
        // 1) Ask the id seam for a numeric id (Stage 0: the DB sequence).
        long id = idGenerator.nextId();
        // 2) Compact that number into a short, URL-safe key.
        String shortKey = Base62Encoder.encode(id);
        // 3) Build the entity and stamp the key on it.
        ShortUrl entity = new ShortUrl(longUrl, expiresAt, owner);
        entity.setShortKey(shortKey);
        // 4) Persist it. save() returns the managed entity (now with its DB id populated).
        return repository.save(entity);
    }

    // readOnly=true is a hint: no writes happen here. Stage 2 uses this exact flag to
    // route the read to a replica — so this method body never changes for that.
    @Transactional(readOnly = true)
    public ShortUrl resolve(String shortKey) {
        // Look the key up; if absent, turn the empty Optional into a 404-mapped exception.
        // This is the read path: Controller -> Service -> (cache, added later) -> Repository.
        return repository.findByShortKey(shortKey)
                .orElseThrow(() -> new NotFoundException("No URL for key: " + shortKey));
    }
}

package com.example.urlshortener;

import jakarta.validation.Valid;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;
import java.net.URI;
import java.time.Instant;

// @RestController = @Controller + @ResponseBody: every method returns DATA (JSON or a
// redirect), not an HTML view name. This is the one HTTP door into the whole system.
@RestController
public class UrlController {

    private final UrlService urlService;

    // @Value injects a config value from application.yml (app.base-url) into this field.
    // We use it to build the full short URL we return.
    private final String baseUrl;

    public UrlController(UrlService urlService,
                         @Value("${app.base-url}") String baseUrl) {
        this.urlService = urlService;
        this.baseUrl = baseUrl;
    }

    // @PostMapping maps HTTP POST /api/urls to this method.
    // @Valid triggers the @NotBlank check on the body; @RequestBody binds JSON -> DTO.
    @PostMapping("/api/urls")
    public ResponseEntity<ShortenResponse> shorten(@Valid @RequestBody ShortenRequest req) {
        // Convert the optional TTL (seconds) into an absolute expiry instant, or null.
        Instant expiresAt = req.ttlSeconds() == null
                ? null
                : Instant.now().plusSeconds(req.ttlSeconds());
        // Delegate ALL the work to the service — the controller stays thin.
        ShortUrl saved = urlService.shorten(req.longUrl(), expiresAt, null);
        // Build the JSON response DTO from the saved entity.
        ShortenResponse body = new ShortenResponse(
                baseUrl + "/" + saved.getShortKey(),
                saved.getShortKey(),
                saved.getExpiresAt());
        // Return 201 Created with the body. ResponseEntity lets us set the status explicitly.
        return ResponseEntity.status(HttpStatus.CREATED).body(body);
    }

    // @GetMapping with a path variable: GET /aB3xQ. @PathVariable pulls 'aB3xQ' out of the URL.
    @GetMapping("/{shortKey}")
    public ResponseEntity<Void> redirect(@PathVariable String shortKey) {
        // Look up the long URL (throws NotFoundException -> 404 if missing).
        ShortUrl target = urlService.resolve(shortKey);
        // Return 302 Found with a Location header pointing at the long URL.
        // We pick 302 (temporary), not 301 (permanent), so browsers don't cache it forever
        // and we keep the chance to count every click later (Stage 4 analytics).
        return ResponseEntity.status(HttpStatus.FOUND)
                .location(URI.create(target.getLongUrl()))
                .build();
    }
}

package com.example.urlshortener;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import java.util.Map;

// @RestControllerAdvice = one place that catches exceptions thrown by ANY @RestController
// and converts them into clean JSON error responses. Keeps try/catch out of controllers.
@RestControllerAdvice
public class GlobalExceptionHandler {

    // @ExceptionHandler says: when a NotFoundException bubbles up, run THIS method.
    @ExceptionHandler(NotFoundException.class)
    public ResponseEntity<Map<String, String>> handleNotFound(NotFoundException ex) {
        // Respond 404 Not Found with a small JSON body { "error": "..." }.
        return ResponseEntity.status(HttpStatus.NOT_FOUND)
                .body(Map.of("error", ex.getMessage()));
    }
}