diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c8aa8cb
--- /dev/null
+++ b/README.md
@@ -0,0 +1,128 @@
+# user-microservice-deploy
+
+Repozytorium **GitOps** dla mikroserwisu [`user-microservice`](../user-microservice). Zawiera
+**manifesty Kubernetes** wdrażanej aplikacji oraz **konfiguracje narzędzi CD** (ArgoCD, FluxCD,
+`kubectl`) używane w pracy magisterskiej porównującej narzędzia CI/CD do budowania i wdrażania
+aplikacji skonteneryzowanych.
+
+Zgodnie z zasadą GitOps stan klastra jest odwzorowaniem zawartości tego repozytorium: potok CI
+z repozytorium aplikacji aktualizuje tutaj tag obrazu, a narzędzie CD wprowadza tę zmianę na
+klaster (przez synchronizację *pull* w ArgoCD/FluxCD lub przez `kubectl apply` w wariancie
+imperatywnym).
+
+---
+
+## Spis treści
+
+- [Rola w architekturze](#rola-w-architekturze)
+- [Manifesty Kubernetes](#manifesty-kubernetes)
+- [Wariant wdrożenia = branch](#wariant-wdrożenia--branch)
+- [Narzędzia CD](#narzędzia-cd)
+  - [kubectl (Jenkins / Woodpecker)](#kubectl-jenkins--woodpecker)
+  - [ArgoCD](#argocd)
+  - [FluxCD](#fluxcd)
+  - [Argo Workflows](#argo-workflows)
+- [Sekrety i tożsamość](#sekrety-i-tożsamość)
+- [Powiązanie z repozytorium aplikacji](#powiązanie-z-repozytorium-aplikacji)
+
+---
+
+## Rola w architekturze
+
+```
+  Potok CI (repo aplikacji)                 to repozytorium (GitOps)                  Klaster AKS
+  ─────────────────────────                 ────────────────────────                 ───────────
+  docker push (tag = SHA)  ──▶  commit: "Changed deployed version to <SHA>"  ──▶  narzędzie CD
+                                (podmiana image w deploy.yaml)                    (apply / sync)
+```
+
+Historia commitów w tym repozytorium to zapis kolejnych wdrożeń — każdy commit typu
+`... Changed deployed version to <SHA>` odpowiada jednemu przebiegowi potoku CI.
+
+## Manifesty Kubernetes
+
+Aplikacja wdrażana jest do namespace `user-microservice`. Zestaw manifestów:
+
+| Plik | Zawartość |
+|------|-----------|
+| `namespace.yaml` | Namespace `user-microservice` |
+| `deploy.yaml` | Deployment + Service dla **MySQL** oraz Deployment + Service dla **API** (to tutaj potok CI podmienia tag obrazu kontenera `api`) |
+| `ingress.yaml` | Ingress (NGINX) wystawiający API pod `user-microservice.marcin00.pl` |
+| `secret-store.yaml` | `SecretProviderClass` (CSI secrets-store) mapujący sekrety z Azure Key Vault na sekrety K8s |
+| `rbac-role.yaml` | `ClusterRoleBinding` dla tożsamości wdrażającej |
+
+> W wariantach **FluxCD** manifesty aplikacji leżą w `apps/user-microservice/`, a konfiguracja
+> klastra w `clusters/prod/`. W pozostałych wariantach manifesty znajdują się w katalogu
+> głównym repozytorium.
+
+## Wariant wdrożenia = branch
+
+Każdy scenariusz porównawczy (kombinacja narzędzia CI i CD) ma osobny branch:
+
+| Branch | Scenariusz | CI | CD |
+|--------|-----------|----|----|
+| `master` | — | — | baza manifestów |
+| `jenkins-kubernetes` | 1 | Jenkins | `kubectl apply` (potok deploy w Jenkins) |
+| `jenkins-argocd-deploy` | 2 | Jenkins | ArgoCD |
+| `jenkins-fluxcd-deploy` | 3 | Jenkins | FluxCD |
+| `woodpecker-deploy` | 4 | Woodpecker | `kubectl apply` (potok deploy w Woodpecker) |
+| `woodpecker-argocd-deploy` | 5 | Woodpecker | ArgoCD |
+| `woodpecker-fluxcd-deploy` | 6 | Woodpecker | FluxCD |
+| `argo-deploy` | 7 | Argo Workflows | Argo Workflows |
+| `argoworkflow-argocd` | 8 | Argo Workflows | ArgoCD |
+| `argoworkflow-fluxcd` / `fluxcd` | 9 | Argo Workflows | FluxCD |
+
+## Narzędzia CD
+
+### kubectl (Jenkins / Woodpecker)
+
+Wariant imperatywny „to samo narzędzie do CI i CD". Potok deploy jest wyzwalany commitem do
+tego repozytorium i wykonuje sekwencję:
+
+1. logowanie do Azure (managed identity) i pobranie kubeconfig (`az aks get-credentials`
+   + `kubelogin`),
+2. `kubectl apply` kolejnych manifestów (`namespace`, `secret-store`, `deploy`, `ingress`),
+3. `kubectl rollout status` — oczekiwanie na gotowość podów,
+4. **health check** aplikacji przez `curl` na `/health` (do skutku lub timeout).
+
+- **Jenkins** — `.jenkins/Jenkinsfile` (+ `Dockerfile`, `podTemplate.yaml`) na branchu
+  `jenkins-kubernetes`.
+- **Woodpecker** — `.woodpecker/build.yaml` na branchu `woodpecker-deploy`.
+
+### ArgoCD
+
+Model GitOps typu *pull*: ArgoCD obserwuje odpowiedni branch tego repozytorium i synchronizuje
+manifesty ze stanem klastra. Manifesty w katalogu głównym repo, wdrożenie wyzwalane commitem
+potoku CI (podmiana taga obrazu).
+
+### FluxCD
+
+Model GitOps typu *pull* oparty na CRD Fluksa (katalog `clusters/prod/`):
+
+| Plik | Rola |
+|------|------|
+| `source.yaml` | `GitRepository` — źródło (ten branch repo), odpytywane co 1 min |
+| `kustomization.yaml` | `Kustomization` — ścieżka `./apps/user-microservice`, `prune: true`, docelowy namespace |
+| `flux-receiver.yaml` | `Receiver` — webhook przyspieszający reakcję na push (bez czekania na interwał) |
+| `source.yaml` / `load-balancer.yaml` / `network-policy.yaml` | Dodatkowa konfiguracja klastra (zależnie od wariantu) |
+
+### Argo Workflows
+
+W scenariuszu 7 (branch `argo-deploy`) rolę CD pełni Argo Workflows: `EventSource` w repo
+aplikacji nasłuchuje również na webhook z tego repozytorium (endpoint
+`user-microservice-deploy`), co pozwala wyzwolić workflow wdrożeniowy po zmianie manifestów.
+
+## Sekrety i tożsamość
+
+- Sekrety aplikacji (`SQLALCHEMY_DATABASE_URI`, hasła MySQL) nie są przechowywane w repo —
+  pochodzą z **Azure Key Vault** i są montowane do podów przez sterownik CSI `secrets-store`
+  (`secret-store.yaml`, `SecretProviderClass` `azure-kvname`).
+- Uwierzytelnianie do ACR/AKS/Key Vault odbywa się przez **managed identity** (bez haseł).
+- Klucz deploy do Gitea oraz `known_hosts` są dostarczane potokom CI jako sekrety narzędzia
+  CI (nie znajdują się w repozytorium).
+
+## Powiązanie z repozytorium aplikacji
+
+Kod aplikacji, definicje potoków CI oraz analiza wyników pomiarów znajdują się w repozytorium
+[`user-microservice`](../user-microservice) — zobacz jego `README.md` po pełny opis architektury,
+scenariuszy pomiarowych i mapy branchy.