khalidelokiely/squash-it

Purpose and Startup

Squash It is a Go URL-shortening service: it creates short hash tokens for long URLs, resolves tokens to destinations, and redirects visit requests while tracking clicks. main.go is the process entry point; dependency construction is centralized in internal/app/provide.go. Runtime configuration is loaded from internal/config/config.go.

HTTP Edge and Routing

A custom router wraps net/http, providing route groups, handler adaptation, options, and serving behavior. Application routes connect HTTP endpoints to handlers; middleware applies cross-cutting controls such as client-based throttling.

• internal/router/router.go

• internal/router/serve.go

• internal/app/routes.go

• internal/app/middleware.go

• internal/app/handlers.go

Application Layer

The app layer owns request/response models and orchestrates encode, decode, and redirect use cases. Handlers parse HTTP DTOs and invoke the service; the service coordinates hashing, Bloom checks, repository persistence, caches, and redirect/click behavior without embedding transport concerns.

• internal/app/model.go

• internal/app/service.go

• internal/app/handlers.go

Persistence and URL Identity

SQLite is the source of truth for URL mappings and click counts. The repository abstracts database operations, including lookup and idempotent find-or-create behavior needed when concurrent or repeated encode requests target an existing long URL. Short tokens are generated with seeded Murmur hashing and retried on collisions.

• internal/db/db.go

• internal/app/repository.go

• internal/hash/hash.go

Encode Control Flow

/encode is rate-limited, then the service generates an 8-character candidate token. A Bloom negative permits an idempotent repository insert; a “maybe present” result triggers DB verification. Matching long URLs reuse their mapping; token collisions retry with another hash seed until success or retry exhaustion. Successful mappings update the Bloom filter.

• internal/app/service.go

• internal/filter/filter.go

• internal/filter/bloom.go

• internal/rate/user_token_bucket.go

Decode and Redirect Read Path

Decode first consults the Bloom filter to reject definite misses cheaply. Possible matches follow an L1/L2 cache pipeline, then SQLite on cache miss. DB hits repopulate cache and Bloom. The visit route follows this resolution path, increments the persisted click count, and returns a 302 Found redirect.

• internal/app/service.go

• internal/cache/pipeline.go

• internal/cache/lru.go

• internal/app/repository.go

State Acceleration and Runtime Infrastructure

The cache pipeline uses in-process LRU as L1 and optional Redis as L2; Redis failure degrades safely to local caching. The Bloom filter is persisted/reconstructed asynchronously and backed up on an interval, guarding DB/cache traffic but allowing false positives. Docker Compose provisions Redis alongside the service; SQLite requires no network dependency.

• internal/cache/redis.go

• internal/cache/provide.go

• internal/filter/persistent_bloom.go

• docker-compose.yml

• Dockerfile