diff --git a/README.md b/README.md
new file mode 100644
index 0000000..20eb0c0
--- /dev/null
+++ b/README.md
@@ -0,0 +1,148 @@
+# GiecChallenge
+
+A full‑stack demo application consisting of an ASP.NET Core backend and a React frontend.  
+The project is container‑based and can be run locally with Docker‑Compose or built and deployed through GitLab CI.
+
+## Table of Contents
+- [Overview](#overview)
+- [Prerequisites](#prerequisites)
+- [Environment Variables](#environment-variables)
+- [Running Locally](#running-locally)
+- [Building & Testing](#building--testing)
+- [Deploying with GitLab CI](#deploying-with-gitlab-ci)
+- [Project Structure](#project-structure)
+- [License](#license)
+
+---
+
+### Overview
+- **Backend**: ASP.NET Core 10.0 API (`backend/GiecChallenge`).  
+  Handles authentication, JWT generation, and CRUD operations for products, purchases, etc.
+- **Frontend**: React (create‑react‑app) (`frontend`).  
+  Consumes the API and provides a UI for managing data.
+- **Infrastructure**: Docker containers for backend, frontend, and PostgreSQL database, orchestrated with `docker‑compose.yml`.
+
+All secrets (DB credentials, JWT secret, passwords, etc.) are externalised to environment variables and **never** committed to source control.
+
+---
+
+### Prerequisites
+- Docker Engine (>= 20.10) with Docker‑Compose support  
+- Git (to clone the repository)  
+- (Optional) GitLab Runner with Docker‑in‑Docker for CI pipelines  
+- Node 14+ (for local frontend development)  
+- .NET 10 SDK (for local backend development)
+
+---
+
+### Environment Variables
+Create a `.env` file at the repository root (or supply variables to your CI environment). Example:
+
+```dotenv
+# Database
+POSTGRES_USER=your_user
+POSTGRES_PASSWORD=your_password
+
+# Connection string (used by the backend)
+ConnectionStrings__PostgreSQL=Host=giecchallenge_db;Port=14432;Database=GiecChallenge;User ID=${POSTGRES_USER};Password=${POSTGRES_PASSWORD};Pooling=true
+
+# JWT configuration
+JWT__ValidAudience=https://giecchallenge-backend.maximeboulay.com
+JWT__ValidIssuer=https://giecchallenge-backend.maximeboulay.com
+JWT__Secret=super_secret_jwt_key
+
+# UI configuration
+REACT_APP_API_URL=http://localhost:17020   # points to the backend container
+
+# Misc
+OriginAllowed=http://localhost:3000
+PasswordHash=some_hash_value
+```
+
+The `appsettings.Development.json` and `appsettings.Docker.json` files reference these variables using the `${VARIABLE_NAME}` syntax.
+
+---
+
+### Running Locally
+1. **Start the stack**
+
+```bash
+docker compose up --build
+```
+
+   - Backend API: `http://localhost:17020` (HTTP) & `https://localhost:17021` (HTTPS)  
+   - Frontend UI: `http://localhost:13000`  
+   - PostgreSQL: `localhost:14432`
+
+2. **Access the UI** in a browser at `http://localhost:13000`.
+
+3. **Stop the stack**
+
+```bash
+docker compose down
+```
+
+---
+
+### Building & Testing
+#### Backend
+```bash
+dotnet restore backend/GiecChallenge/GiecChallenge.csproj
+dotnet build backend/GiecChallenge/GiecChallenge.csproj -c Release
+dotnet test backend/GiecChallenge.test/GiecChallenge.test.csproj
+```
+
+#### Frontend
+```bash
+cd frontend
+npm ci
+npm run build   # produces ./frontend/build
+```
+
+---
+
+### Deploying with GitLab CI
+The repository contains a `.gitlab-ci.yml` defining the following stages:
+
+1. **restore** – restores NuGet packages and installs Node dependencies.  
+2. **build** – builds the .NET project and the React app.  
+3. **test** – runs backend unit tests.  
+4. **docker_build** – builds Docker images for both services and pushes them to the GitLab Container Registry.  
+5. **deploy** – placeholder stage for your production deployment (e.g., Kubernetes, Docker Swarm, or a VM).
+
+The CI pipeline expects the following CI/CD variables to be defined in GitLab:
+
+- `CI_REGISTRY_USER`, `CI_REGISTRY_PASSWORD`, `CI_REGISTRY`, `CI_REGISTRY_IMAGE` (provided automatically by GitLab).  
+- All custom variables from the `.env` file (e.g., `POSTGRES_USER`, `POSTGRES_PASSWORD`, `JWT__Secret`, etc.).
+
+Push a branch, and GitLab will automatically run the pipeline. Merge to `main` to trigger the `deploy` stage placeholder.
+
+---
+
+### Project Structure
+
+```
+├── backend/
+│   └── GiecChallenge/
+│       ├── Dockerfile          # Backend container image
+│       ├── appsettings.*.json  # Configuration files (environment‑variable placeholders)
+│       ├── Controllers/ ...
+│       └── *.csproj
+├── frontend/
+│   ├── Dockerfile              # Frontend container image
+│   ├── package.json
+│   └── src/ …
+├── docker-compose.yml          # Local orchestration
+├── .gitlab-ci.yml              # CI pipeline definition
+├── .env                        # Example env file (do not commit secrets)
+└── README.md                   # You are reading it now
+```
+
+---
+
+### License
+This project is provided for educational purposes. Feel free to adapt and extend it under the terms of the MIT License.
+
+---
+
+**Enjoy!** If you encounter any issues, verify that all required environment variables are defined and that Docker is running with sufficient resources.
\ No newline at end of file