diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5c77dc9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,98 @@
+# Overview
+
+This repository contains a collection of NixOS configurations, modules, and tools designed to make system management more efficient. The goal is to make wiring easy and deployment straight forward.
+
+## Features
+
+- 🏗️ Flake-based configuration management
+- 🔐 Secrets management with sops-nix
+- 🚀 Deployment tools with deploy-rs
+- 🔍 Package search with nix-index-database
+- 🌐 Remote installation support with nixos-anywhere
+
+## Prerequisites
+
+- Nix with flakes enabled
+- direnv
+- just
+
+## Quick Start
+
+
+1. Enter the development shell:
+    only needed if missing direnv
+   ```bash
+   just dev
+   ```
+
+2. Update dependencies:
+   ```bash
+   just update
+   ```
+
+3. Check the configuration:
+   ```bash
+   just check
+   ```
+
+## Directory Structure
+
+```
+.
+├── configurations/     # System configurations
+│   └── nixos/        # NixOS system configurations
+├── modules/          # Reusable NixOS and flake modules
+│   ├── flake/       # Flake-specific modules
+│   └── nixos/       # NixOS modules
+├── overlays/         # Custom package overlays
+├── packages/         # Custom packages
+├── flake.nix        # Main flake configuration
+├── flake.lock       # Flake lock file
+└── justfile         # Common commands
+```
+
+## Available Commands
+
+The repository includes several convenient commands via `just`:
+
+- `just` - List all available commands
+- `just update` - Update nix flake dependencies
+- `just lint` - Lint nix files
+- `just check` - Check nix flake
+- `just dev` - Enter development shell
+- `just run` - Activate the configuration
+
+## Configuration
+
+### System Configuration
+
+System configurations are located in `configurations/nixos/`. Each system should have its own directory with the following structure:
+
+```
+configurations/nixos/<system-name>/
+├── default.nix    # Main system configuration
+├── hardware.nix        # Hardware-specific configuration
+└── secrets/           # Encrypted secrets (if using sops-nix)
+```
+
+## Development
+
+### Adding New Modules
+
+1. Create a new module in `modules/nixos/` or `modules/flake/`
+2. Update the flake.nix to include the new module
+3. Test the module with `just check`
+
+### Adding New Packages
+
+1. Create a new package in `packages/<name>/default.nix`
+2. Update the flake.nix to include the new package
+3. Test the package with `just check`
+
+
+## Acknowledgments
+
+- [NixOS](https://nixos.org/)
+- [deploy-rs](https://github.com/serokell/deploy-rs)
+- [sops-nix](https://github.com/Mic92/sops-nix)
+- [disko](https://github.com/nix-community/disko)