Add project documentation

Author: selimyanat

README.md

@@ -0,0 +1,42 @@
+# Tiny URL Like Application
+
+![Tiny URL Like Application](docs/tiny-url-application.png)
+
+Why do we need in a first place a URL shortener such as [Tiny url](http://tinyurl.com) ? Simply put, it allows us to 
+shorten long URLs and make message more concise and also save a lot of space when used in social media like tweeter 
+where messages are constrained in terms of size. When a user hit the shortened url it is redirected to the original URL.
+
+However, behind this simplicity, lies many technical challenges. For example:
+* How do we generate a short URL? 
+* How do we ensure that short URL that is unique and does not collide with other URLs ? 
+* How do we store the mapping between the short URL and the original URL ? 
+* How do we handle high traffic and ensure that the service is scalable ?
+
+This repository contains a simple implementation of a URL shortener service. It is not meant to be a production-ready 
+service, but rather a proof of concept to demonstrate the basic functionality of a URL shortener. In addition, a system
+design document is provided to explain the design choices made in the implementation. 
+
+Happy learning !
+
+# Table of contents
+
+* [How to run the application locally](docs/how-to-build-run-the-app-locally.md)
+* [System design](docs/system-design.md)
+* [References](docs/references.md)
+* Ensure interoperability between backend and frontend: consumer driven contract testing
+* References
+
+
+
+
+
+
+
+# How to run the application
+
+# System design 
+
+# References
+
+* [System Design : Scalable URL shortener service like TinyURL](https://medium.com/@sandeep4.verma/system-design-scalable-url-shortener-service-like-tinyurl-106f30f23a82)
+* 

docs/how-to-build-run-the-app-locally.md

@@ -0,0 +1,64 @@
+# 🛠 Prerequisites
+
+* Node v18.18+
+* Docker v27+
+* Yarn or Npm
+
+# 🔨 Build & Test
+
+You can build and test the application manually by following the instructions below, or refer to the CI pipeline defined 
+in `.github/workflows/ci.yaml` for automated testing.
+
+## WebApp
+
+```bash
+cd webapp
+cp .env-dev .env
+yarn install
+yarn test
+```
+
+## API server
+* CD to the `api` directory
+* Open a terminal and run the following command to install dependencies:
+```bash
+cd api
+cp .env-dev .env
+yarn install
+yarn test
+```
+
+# 🚀 Running the App
+
+## Option 1: Run Everything via Docker Compose
+The fastest way to launch the entire stack (API, WebApp, Redis, DynamoDB, RedisInsight) is with Docker Compose.
+```bash
+docker compose -f docker-compose.yml up -d --build
+```
+This builds and starts all services defined in the docker-compose.yml.
+
+## Option 2: Run Infrastructure with Docker + App Locally from Your IDE or Terminal
+
+### Step 1: Start Infrastructure Only
+
+```bash
+docker compose up -d redis redisinsight dynamodb dynamodb-init
+```
+ℹ️ Optional: Use In-Memory Mode for Fast Testing
+You can run the API server in in-memory mode (without Redis or DynamoDB) by setting the following environment variable 
+in your .env file:
+```
+USE_PERSISTENT_STORAGE=false
+```
+### Step 2: Run WebApp Locally
+```bash
+cd webapp
+cp .env-dev .env
+yarn start:dev
+```
+### Step 3: Run API Server Locally
+```bash
+cd api
+cp .env-dev .env
+yarn start:dev
+```

docs/references.md

@@ -0,0 +1 @@
+# System Design