diff --git a/Dockerfile b/Dockerfile
index 6de4317..cd277ab 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -8,6 +8,6 @@ RUN pip install --no-cache-dir -r requirements.txt
 
 COPY . .
 
-EXPOSE 8000
+EXPOSE 9995
 
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
\ No newline at end of file
+CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "9995"]
\ No newline at end of file
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..5259bc0
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,11 @@
+run:
+	uvicorn app.main:app --reload --port 9995
+
+test:
+	pytest --cov=app --cov-report=term-missing
+
+docker:
+	docker compose up --build
+
+lint:
+	ruff check .
\ No newline at end of file
diff --git a/README.md b/README.md
index 0896889..97f609d 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,38 @@
-# URL-shortener
-URL-shortener project to showcase python use
+# URL Shortener API
+
+Production-ready URL Shortener built with FastAPI, PostgreSQL, Docker, and Alembic.
+
+![Tests](https://img.shields.io/badge/tests-passing-brightgreen)
+![Coverage](https://img.shields.io/badge/coverage-90%25-brightgreen)
+![Python](https://img.shields.io/badge/python-3.12-blue)
+
+## Techstack
+
+FastAPI, PostgreSQL, SQLAlchemy 2.0, Alembic, Docker, Pytest and Pydantic v2
+
+## Features
+
+Shorten URLs, Redirect, Click tracking, Stats endpoint, Collision handling, 90%+ test coverage, Dockerized and Alembic migrations
+
+## Local Setup
 
-## Create venv
 ```bash
-cd /opt/kjc/int/URL-shortener
+cd <your-repo-url>
 python3 -m venv venv
 source venv/bin/activate
 ```
 
-## Run locally
-```bash
-python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+Create .env:
 ```
+DATABASE_URL=sqlite:///./test.db
+BASE_URL=http://localhost:8000
+```
+
+Run:
+```bash
+python -m uvicorn app.main:app --reload --host 0.0.0.0 --port 9995
+```
+
 Then check:<br> 
 http://localhost:9995<br>
 http://localhost:9995/docs
@@ -19,21 +40,19 @@ http://localhost:9995/docs
 Test Short URL Endpoint:<br>
 http://localhost:9995/shorten
 
-## Running a test
+## Run Tests
 ```bash
-PYTHONPATH=./ pytest
-export PYTHONPATH=$(pwd)
-python -m pytest --cov=app --cov-report=term-missing
+pytest --cov=app --cov-report=term-missing
 ```
 
 ## Running Alembic revision
 ```bash
-cd /opt/kjc/int/URL-shortener
+cd <your-repo-url>
 alembic revision --autogenerate -m "create urls table"
 ```
 
 ## Running project in Docker container
 ```bash
-cd /opt/kjc/int/URL-shortener
+cd <your-repo-url>
 docker compose up --build
 ```
\ No newline at end of file
diff --git a/alembic/env.py b/alembic/env.py
index 4125426..4d83369 100644
--- a/alembic/env.py
+++ b/alembic/env.py
@@ -3,7 +3,6 @@ from sqlalchemy import engine_from_config, pool
 from logging.config import fileConfig
 
 from app.db.base import Base
-from app.db import models
 from app.core.config import settings
 
 target_metadata = Base.metadata
diff --git a/alembic/versions/0132ba841ec5_create_urls_table.py b/alembic/versions/0132ba841ec5_create_urls_table.py
index a6633ce..8685400 100644
--- a/alembic/versions/0132ba841ec5_create_urls_table.py
+++ b/alembic/versions/0132ba841ec5_create_urls_table.py
@@ -7,8 +7,6 @@ Create Date: 2026-03-02 09:13:50.764599
 """
 from typing import Sequence, Union
 
-from alembic import op
-import sqlalchemy as sa
 
 
 # revision identifiers, used by Alembic.
diff --git a/app/api/routes.py b/app/api/routes.py
index 164d9e7..14391f7 100644
--- a/app/api/routes.py
+++ b/app/api/routes.py
@@ -27,10 +27,16 @@ def shorten_url(
     request: URLCreate,
     db: Session = Depends(get_db),
 ):
-    short_url = url_service.create_short_url(db, str(request.url))
+    normalized_url = str(request.url).rstrip("/")
+    short_url = url_service.create_short_url(db, normalized_url)
     return {"short_url": short_url}
 
 
+@router.get("/health")
+def health():
+    return {"message": "healthy"}
+
+
 @router.get("/{short_code}")
 def redirect_to_url(
     short_code: str,
@@ -63,8 +69,3 @@ def get_url_stats(
         )
 
     return stats
-
-
-@router.get("/health", response_model=MessageResponse)
-def health_check():
-    return {"message": "healthy"}
\ No newline at end of file
diff --git a/app/main.py b/app/main.py
index 256bcea..0d93ad3 100644
--- a/app/main.py
+++ b/app/main.py
@@ -1,5 +1,6 @@
 # app/main.py
 
+import logging
 from fastapi import FastAPI
 from contextlib import asynccontextmanager
 from app.core.config import settings
@@ -7,11 +8,18 @@ from app.db.session import engine
 from app.db.base import Base
 from app.api.routes import router
 
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+)
+
+import os
+from contextlib import asynccontextmanager
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-
-    Base.metadata.create_all(bind=engine)
+    if os.getenv("TESTING") != "1":
+        Base.metadata.create_all(bind=engine)
     yield
 
 def create_app() -> FastAPI:
diff --git a/app/schemas/url.py b/app/schemas/url.py
index ab24c28..7ef7c14 100644
--- a/app/schemas/url.py
+++ b/app/schemas/url.py
@@ -14,11 +14,11 @@ class URLResponse(BaseModel):
 
 
 class URLStatsResponse(BaseModel):
-    original_url: HttpUrl
+    original_url: str
     clicks: int
     created_at: datetime
-    last_accessed: Optional[datetime] = None
-
+    last_accessed: Optional[datetime]
+    
 
 class MessageResponse(BaseModel):
     message: str
\ No newline at end of file
diff --git a/app/services/url_service.py b/app/services/url_service.py
index 7c2300d..85d0ac2 100644
--- a/app/services/url_service.py
+++ b/app/services/url_service.py
@@ -18,9 +18,12 @@ def create_short_url(db: Session, original_url: str) -> str:
     Create a shortened URL or return existing one if already present.
     """
 
+    # ✅ Normalize FIRST (critical fix)
+    normalized_url = original_url.rstrip("/")
+
     # 1️⃣ Check if URL already exists
     existing = db.execute(
-        select(URL).where(URL.original_url == original_url)
+        select(URL).where(URL.original_url == normalized_url)
     ).scalar_one_or_none()
 
     if existing:
@@ -37,7 +40,7 @@ def create_short_url(db: Session, original_url: str) -> str:
         if not collision:
             new_url = URL(
                 short_code=short_code,
-                original_url=original_url,
+                original_url=normalized_url,  # ✅ store normalized version
             )
             db.add(new_url)
             db.commit()
@@ -45,9 +48,8 @@ def create_short_url(db: Session, original_url: str) -> str:
 
             return f"{settings.base_url}/{new_url.short_code}"
 
-    # If we somehow fail multiple times
     raise RuntimeError("Failed to generate unique short code")
-
+    
 
 def get_original_url(db: Session, short_code: str) -> Optional[str]:
     """
diff --git a/app/tests/conftest.py b/app/tests/conftest.py
index 55dffc8..a46cd1e 100644
--- a/app/tests/conftest.py
+++ b/app/tests/conftest.py
@@ -2,6 +2,7 @@
 
 import pytest
 from sqlalchemy import create_engine
+from sqlalchemy.pool import StaticPool
 from sqlalchemy.orm import sessionmaker
 from fastapi.testclient import TestClient
 
@@ -9,21 +10,18 @@ from app.main import app
 from app.db.base import Base
 from app.db.session import get_db
 
+import os
+os.environ["TESTING"] = "1"
 
 # Use in-memory SQLite for tests
 TEST_DATABASE_URL = "sqlite+pysqlite:///:memory:"
 
-
 @pytest.fixture(scope="function")
 def db_session():
-    """
-    Creates a new database session for a test.
-    Rolls back everything after test finishes.
-    """
-
     engine = create_engine(
         TEST_DATABASE_URL,
         connect_args={"check_same_thread": False},
+        poolclass=StaticPool,
     )
 
     TestingSessionLocal = sessionmaker(
@@ -32,7 +30,6 @@ def db_session():
         bind=engine,
     )
 
-    # Create tables
     Base.metadata.create_all(bind=engine)
 
     db = TestingSessionLocal()
diff --git a/app/tests/test_config.py b/app/tests/test_config.py
new file mode 100644
index 0000000..c4bbae9
--- /dev/null
+++ b/app/tests/test_config.py
@@ -0,0 +1,16 @@
+from app.core.config import get_settings
+
+def test_get_settings_returns_same_instance():
+    s1 = get_settings()
+    s2 = get_settings()
+
+    assert s1 is s2  # lru_cache should return same instance
+
+def test_default_settings_values():
+    settings = get_settings()
+
+    assert settings.app_name == "URL Shortener"
+    assert settings.host == "0.0.0.0"
+    assert settings.port == 8000
+    assert settings.debug is True
+    assert isinstance(settings.allowed_hosts, list)
\ No newline at end of file
diff --git a/app/tests/test_models.py b/app/tests/test_models.py
new file mode 100644
index 0000000..fa813a2
--- /dev/null
+++ b/app/tests/test_models.py
@@ -0,0 +1,32 @@
+from app.db.models import URL
+
+def test_url_model_defaults(db_session):
+    url = URL(
+        short_code="abc123",
+        original_url="https://example.com",
+    )
+
+    db_session.add(url)
+    db_session.commit()
+    db_session.refresh(url)
+
+    assert url.id is not None
+    assert url.clicks == 0
+    assert url.created_at is not None
+    assert url.last_accessed is None
+
+def test_url_repr(db_session):
+    url = URL(
+        short_code="xyz789",
+        original_url="https://repr-test.com",
+    )
+
+    db_session.add(url)
+    db_session.commit()
+    db_session.refresh(url)
+
+    repr_output = repr(url)
+
+    assert "URL" in repr_output
+    assert "xyz789" in repr_output
+    assert "https://repr-test.com" in repr_output
\ No newline at end of file
diff --git a/app/tests/test_routes.py b/app/tests/test_routes.py
index c1edf37..2be8365 100644
--- a/app/tests/test_routes.py
+++ b/app/tests/test_routes.py
@@ -1,8 +1,5 @@
 # app/tests/test_routes.py
 
-import pytest
-
-
 def test_home(client):
     response = client.get("/")
     assert response.status_code == 200
diff --git a/app/tests/test_services.py b/app/tests/test_services.py
new file mode 100644
index 0000000..64ef768
--- /dev/null
+++ b/app/tests/test_services.py
@@ -0,0 +1,106 @@
+import pytest
+from unittest.mock import patch
+
+from app.services import url_service
+from app.db.models import URL
+
+
+def test_create_short_url_creates_new(db_session):
+    short_url = url_service.create_short_url(
+        db_session,
+        "https://new-url.com",
+    )
+
+    assert short_url.startswith("http://")
+
+    entry = db_session.query(URL).first()
+    assert entry is not None
+    assert entry.original_url == "https://new-url.com"
+
+
+def test_create_short_url_returns_existing(db_session):
+    first = url_service.create_short_url(
+        db_session,
+        "https://duplicate.com",
+    )
+
+    second = url_service.create_short_url(
+        db_session,
+        "https://duplicate.com",
+    )
+
+    assert first == second
+    assert db_session.query(URL).count() == 1
+
+
+def test_create_short_url_collision_failure(db_session):
+    with patch(
+        "app.services.url_service.generate_short_code",
+        return_value="fixedcode",
+    ):
+        # First insert works
+        url_service.create_short_url(db_session, "https://a.com")
+
+        # Force collision repeatedly
+        with pytest.raises(RuntimeError):
+            url_service.create_short_url(db_session, "https://b.com")
+
+
+def test_get_original_url_success(db_session):
+    short_url = url_service.create_short_url(
+        db_session,
+        "https://lookup.com",
+    )
+    code = short_url.split("/")[-1]
+
+    original = url_service.get_original_url(db_session, code)
+
+    assert original == "https://lookup.com"
+
+
+def test_get_original_url_not_found(db_session):
+    result = url_service.get_original_url(db_session, "missing")
+    assert result is None
+
+
+def test_increment_clicks_success(db_session):
+    short_url = url_service.create_short_url(
+        db_session,
+        "https://click-test.com",
+    )
+    code = short_url.split("/")[-1]
+
+    success = url_service.increment_clicks(db_session, code)
+
+    assert success is True
+
+    entry = db_session.query(URL).first()
+    assert entry.clicks == 1
+    assert entry.last_accessed is not None
+
+
+def test_increment_clicks_not_found(db_session):
+    result = url_service.increment_clicks(db_session, "missing")
+    assert result is False
+
+
+def test_get_stats_success(db_session):
+    short_url = url_service.create_short_url(
+        db_session,
+        "https://stats.com",
+    )
+    code = short_url.split("/")[-1]
+
+    url_service.increment_clicks(db_session, code)
+
+    stats = url_service.get_stats(db_session, code)
+
+    assert stats is not None
+    assert stats["original_url"] == "https://stats.com"
+    assert stats["clicks"] == 1
+    assert stats["created_at"] is not None
+
+
+def test_get_stats_not_found(db_session):
+    stats = url_service.get_stats(db_session, "missing")
+    assert stats is None
\ No newline at end of file
diff --git a/app/tests/test_utils.py b/app/tests/test_utils.py
new file mode 100644
index 0000000..9ae308f
--- /dev/null
+++ b/app/tests/test_utils.py
@@ -0,0 +1,19 @@
+import string
+from app.utils.short_code import generate_short_code
+
+def test_generate_short_code_length():
+    code = generate_short_code(8)
+    assert len(code) == 8
+
+def test_generate_short_code_is_alphanumeric():
+    code = generate_short_code(12)
+    allowed = string.ascii_letters + string.digits
+
+    for char in code:
+        assert char in allowed
+
+def test_generate_short_code_randomness():
+    code1 = generate_short_code()
+    code2 = generate_short_code()
+
+    assert code1 != code2  # extremely unlikely to fail
\ No newline at end of file
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..6f42fb5
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,6 @@
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.pytest.ini_options]
+pythonpath = ["."]
\ No newline at end of file
diff --git a/requirements.txt b/requirements.txt
index 0c2599e..36e12fa 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -6,4 +6,5 @@ alembic==1.14.1
 pydantic-settings==2.8.1
 
 pytest==8.3.5
-pytest-cov==5.0.0
\ No newline at end of file
+pytest-cov==5.0.0
+ruff==0.15.4
\ No newline at end of file