diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..b9cf175
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,124 @@
+# Kubernetes Cluster Configuration
+
+A comprehensive Helm-based Kubernetes cluster setup with multiple applications and services organized by function.
+
+## 📁 Project Structure
+
+### Core Infrastructure
+
+#### **Cluster**
+- Storage class configuration for persistent volumes
+
+#### **Traefik** (`traefik/`)
+- Ingress controller and reverse proxy
+- Routes external traffic to internal services
+- Helm values configuration included
+
+#### **Shared Database** (`shared-db/`)
+- Centralized PostgreSQL database instance
+- Shared across multiple applications
+- Persistent volume and claim configuration
+- NodePort service for external access
+
+### Applications
+
+#### **Bitwarden** (`bitwarden/`)
+- Password manager and secrets vault
+- Full Helm chart with templates and customizable values
+- Persistent storage configuration
+
+#### **Vaultwarden** (`vaultwarden/`)
+- Open-source Bitwarden alternative
+- Complete Helm chart with deployment templates
+- Ingress, service, and persistence configuration
+
+#### **Gitea** (`gitea/`)
+- Git hosting service
+- Persistent volume and PostgreSQL backed
+- Values configuration for customization
+
+#### **Nextcloud** (`nextcloud/`)
+- File sync, sharing, and collaboration platform
+- Separate persistent volumes for data and PostgreSQL
+- Notification push service included
+- Custom ingress configuration
+
+#### **Immich** (`immich/`)
+- Photo and video backup service
+- Sub-chart for PostgreSQL database management
+- Master node persistent volume
+- PostgreSQL and application storage
+
+#### **Linkwarden Stack** (`linkwarden-stack/`)
+- Link management and bookmarking service
+- Complete Helm chart with ConfigMap, deployment, and ingress
+- Persistent storage configuration
+
+#### **Mumble** (`mumble/`)
+- Voice communication and VoIP service
+- Helm values for configuration
+
+#### **Letsencrypt** (`letsencrypt/`)
+- Automated SSL certificate provisioning
+- Integrations with ingress controllers
+
+### Observability & Monitoring
+
+#### **Observability Stack** (`observability/`)
+
+##### **Prometheus** (`observability/prometheus/`)
+- Metrics collection and time-series database
+- Custom storage class for performance
+- Persistent volume configuration
+
+##### **Loki** (`observability/loki/`)
+- Log aggregation system
+- Companion to Prometheus
+- Dedicated storage configuration
+
+##### **Grafana** (`observability/grafana/`)
+- Metrics and logs visualization
+- Loki backend for log exploration
+- Dashboard and alerting capabilities
+
+##### **Alloy** (`observability/alloy/`)
+- Telemetry collection agent
+- Data collection for Prometheus and Loki
+
+## 🚀 Deployment
+
+Each service is configured as a Helm chart with:
+- `values.yaml` - Configuration and customization
+- `Chart.yaml` - Chart metadata (where applicable)
+- `templates/` - Kubernetes resource templates
+- Persistent volume (PV) and persistent volume claim (PVC) for stateful services
+
+### Quick Start
+
+```bash
+# Add Helm repositories as needed
+helm repo add <repo-name> <repo-url>
+helm repo update
+
+# Deploy a service
+helm install <release-name> <chart-path> -f <chart-path>/values.yaml -n <namespace>
+```
+
+## 📝 Storage Configuration
+
+All persistent services include:
+- **pv-\*.yaml** - PersistentVolume definitions
+- **pvc-\*.yaml** - PersistentVolumeClaim definitions
+- Reference storage class configurations
+
+## 🔗 Ingress Routes
+
+Traefik handles ingress routing with:
+- `ingress.yaml` templates in major services
+- SSL termination via Letsencrypt
+- Pretty hostname routing (e.g., `bitwarden.example.com`)
+
+## 📚 Additional Resources
+
+- [backup.md](backup.md) - Backup and recovery procedures
+- Individual service notes in each subdirectory (notes.md, NOTES.md)