readme

README.md

@@ -0,0 +1,84 @@
+# URL Shortener - Distributed Systems Learning Project
+
+A URL shortening service designed to teach distributed systems concepts.
+
+## Architecture
+
+```
+[Client] --> [Nginx LB] --> [API Server 1] --> [Redis Cache] --> [PostgreSQL]
+                        --> [API Server 2] -->
+                        --> [API Server 3] -->
+```
+
+## Concepts Covered
+
+| Concept | Implementation |
+|---------|----------------|
+| Load Balancing | Nginx with least_conn algorithm |
+| Caching | Redis with read-through pattern |
+| Unique ID Generation | Snowflake IDs (Twitter-style) |
+| Encoding | Base62 for short URLs |
+| Rate Limiting | Nginx rate limiting (10 req/sec/IP) |
+| Async Processing | Fire-and-forget click tracking |
+
+## Quick Start
+
+```bash
+# Start all services
+docker compose up -d
+
+# Scale API servers to 3 instances
+docker compose up -d --scale api=3
+
+# Test the service
+curl -X POST http://localhost/shorten \
+  -H "Content-Type: application/json" \
+  -d '{"url": "https://example.com/very/long/path"}'
+
+# Follow the redirect
+curl -L http://localhost/{short_code}
+
+# Get stats
+curl http://localhost/stats/{short_code}
+```
+
+## Local Development (without Docker)
+
+```bash
+# Install dependencies
+uv venv
+source .venv/bin/activate
+uv pip install -e ".[dev]"
+
+# Start PostgreSQL and Redis (via Docker)
+docker compose up -d postgres redis
+
+# Run the API server
+uvicorn app.main:app --reload
+```
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | /shorten | Create a short URL |
+| GET | /{code} | Redirect to original URL |
+| GET | /stats/{code} | Get click statistics |
+| GET | /health | Health check |
+
+## File Structure
+
+```
+.
+|-- app/
+|   |-- main.py       # FastAPI application
+|   |-- encoding.py   # Base62 encoding
+|   |-- snowflake.py  # Distributed ID generation
+|-- db/
+|   |-- init.sql      # Database schema
+|-- nginx/
+|   |-- nginx.conf    # Load balancer config
+|-- docker-compose.yml
+|-- Dockerfile
+|-- pyproject.toml
+```