---
title: Overview
description: Small, agent-operable URL shortener. Correctness and observability over scale.
---

# Shortly Documentation

**Shortly** is a lightweight, agent-operable URL shortener built on **.NET 10** (Minimal API) and governed by a **Dart local steward** (CLI + MCP).

The project is designed to demonstrate first-class software stewardship, where a complete repository—including charter, decisions, operational guides, benchmarks, and code intelligence—can be cloned and operated by both humans and autonomous agents with zero hidden context.

---

## 🧭 Core Highlights

| Feature | Design Stance |
|---|---|
| **Single Shared Pool** | All shortened URLs share a flat global pool. Shortening the same URL twice creates distinct codes ([ADR 0001](/decisions/0001-single-shared-pool)). |
| **Pure Base-N Encoding** | Deterministic mathematical encoding mapping sequential IDs to Base62 alphanumeric codes ([ADR 0003](/decisions/0003-sequential-base-n-codes)). |
| **Soft Expiry & Check-on-Read** | Expiration is evaluated dynamically when links are accessed. Expired links return `410 Gone` without background sweep workers ([ADR 0004](/decisions/0004-soft-expiry-check-on-read)). |
| **Complete Audit Log** | Every redirect attempt—successful or failed—is persisted with timestamp, IP, User-Agent, and failure reason. |
| **Embedded SQLite with WAL** | Single-file zero-config storage with Write-Ahead Logging for high-throughput concurrent reads ([ADR 0005](/decisions/0005-sqlite-wal)). |
| **Dual-Path Architecture** | The .NET runtime has zero dependencies on Node, Dart, or Docker. Dart and Node form the developer/stewardship toolchain ([ADR 0009](/decisions/0009-local-stewardship-stack)). |

---

## 🚀 Getting Started

Jump straight into the guide:

- **[North Star](/NORTH_STAR)** — Charter, non-goals, and stewardship stance.
- **[Quickstart](/quickstart)** — Step-by-step setup from clone to shortening your first URL.
- **[Architecture](/architecture)** — Detailed domain model, storage, and state transitions.
- **[API Reference](/api/public)** — Complete HTTP API reference and curl examples.
- **[Dart Local Steward & MCP](/stewardship/dart-cli-mcp)** — Operate Shortly via CLI and AI agent tools.
- **[Design FAQ](/DESIGN_FAQ)** & **[DX FAQ](/DX_FAQ)** — Standing *why* and operational *how*.
- **[Architecture Decisions](/decisions/index)** — Immutable record of design choices (ADRs 0001–0009).