diff --git a/.envrc.example b/.envrc.example
new file mode 100644
index 0000000..d288315
--- /dev/null
+++ b/.envrc.example
@@ -0,0 +1,48 @@
+# Example .envrc for direnv
+# Copy this to your project directory and customize as needed
+
+# Load a Nix shell environment
+# Uncomment one of these based on your project type:
+
+# For a simple shell with specific packages:
+# use nix
+
+# For a flake-based project:
+# use flake
+
+# For a custom shell.nix:
+# use nix
+
+# Watch for changes in these files (will reload direnv when they change):
+# watch_file shell.nix
+# watch_file flake.nix
+# watch_file flake.lock
+
+# Layout: Load programming language environments
+# Uncomment the one you need:
+
+# Python with virtualenv:
+# layout python python3
+
+# Python with specific version:
+# layout python python3.11
+
+# Node.js:
+# layout node
+
+# Ruby:
+# layout ruby
+
+# Example: Set environment variables
+# export DATABASE_URL="postgresql://localhost/mydb"
+# export DEBUG="true"
+
+# Example: Add local bin to PATH
+# PATH_add ./bin
+
+# Example: Load secrets from a file (never commit this file!)
+# dotenv .env.local
+
+# For this repo's devshell scripts:
+# After running make-py-devshell, make-cpp-devshell, etc.
+# An .envrc will be automatically created in your project directory
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..92b3dad
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,163 @@
+# Contributing to NixOS Dotfiles
+
+First off, thanks for taking the time to contribute! 🎉
+
+## For New Users
+
+If you're new to this repository:
+
+1. **Read the documentation**
+   - [Quick Start Guide](docs/QUICK_START.md)
+   - [Architecture Overview](docs/ARCHITECTURE.md)
+   - [Module Guide](docs/MODULE_GUIDE.md)
+
+2. **Understand the structure**
+   - `hosts/` - Host-specific configurations
+   - `modules/nixos/` - System-level modules
+   - `modules/home-manager/` - User-level modules
+   - `config/` - Application dotfiles
+
+## Making Changes
+
+### For Your Own Fork
+
+1. **Clone and customize**
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/nixos-dotfiles ~/nixos-dotfiles
+   cd ~/nixos-dotfiles
+   ```
+
+2. **Update personal information**
+   - Change username in `hosts/nixos-btw/home.nix` and `modules/nixos/core.nix`
+   - Update Git info in `modules/home-manager/git.nix`
+   - Copy your hardware config: `sudo cp /etc/nixos/hardware-configuration.nix hosts/nixos-btw/`
+
+3. **Test your changes**
+   ```bash
+   make build  # Test build without applying
+   make test   # Test without making it permanent
+   make switch # Apply permanently
+   ```
+
+### For Contributing Back
+
+1. **Fork the repository**
+
+2. **Create a feature branch**
+   ```bash
+   git checkout -b feature/my-awesome-feature
+   ```
+
+3. **Make your changes**
+   - Follow the existing code style
+   - Add comments for complex configurations
+   - Update documentation if needed
+
+4. **Test thoroughly**
+   ```bash
+   make check  # Validate flake
+   make build  # Test build
+   ```
+
+5. **Commit with clear messages**
+   ```bash
+   git commit -m "Add: Feature description"
+   ```
+
+   Use prefixes:
+   - `Add:` - New feature
+   - `Fix:` - Bug fix
+   - `Update:` - Update existing feature
+   - `Docs:` - Documentation changes
+   - `Refactor:` - Code restructuring
+
+6. **Push and create Pull Request**
+   ```bash
+   git push origin feature/my-awesome-feature
+   ```
+
+## Code Style
+
+### Nix Files
+
+- Use 2 spaces for indentation
+- Add comments for non-obvious configurations
+- Group related settings together
+- Keep modules focused on single responsibilities
+
+Example:
+```nix
+{ pkgs, ... }:
+
+{
+  # Audio configuration
+  services.pipewire = {
+    enable = true;
+    pulse.enable = true;  # PulseAudio compatibility
+  };
+}
+```
+
+### Comments
+
+- Explain **why**, not **what** (the code shows what)
+- Add comments for hardware-specific tweaks
+- Document any workarounds or hacks
+
+## Module Guidelines
+
+### Creating New Modules
+
+1. **Keep it focused** - One module = One domain
+2. **Make it reusable** - Avoid hardcoding user-specific values
+3. **Document it** - Add comments and update MODULE_GUIDE.md
+4. **Test it** - Ensure it builds and works
+
+### Module Template
+
+```nix
+# modules/nixos/my-feature.nix
+{ config, pkgs, ... }:
+
+{
+  # Brief description of what this module does
+  
+  # Group related configurations
+  services.my-service = {
+    enable = true;
+    # Add inline comments for complex settings
+    setting = "value";
+  };
+}
+```
+
+## Submitting Issues
+
+### Bug Reports
+
+Include:
+- NixOS version (`nixos-version`)
+- Steps to reproduce
+- Expected vs actual behavior
+- Error messages (if any)
+
+### Feature Requests
+
+Include:
+- Clear description of the feature
+- Use case / motivation
+- Examples from other configs (if applicable)
+
+## Questions?
+
+- Open an issue for configuration questions
+- Check existing issues and PRs first
+- Be respectful and patient
+
+## License
+
+By contributing, you agree that your contributions will be included under the same terms as the original repository.
+
+---
+
+Thank you for contributing! 🚀
diff --git a/Makefile b/Makefile
new file mode 100644
index 0000000..1090a34
--- /dev/null
+++ b/Makefile
@@ -0,0 +1,49 @@
+.PHONY: help switch test build update clean check fmt
+
+# Default target
+help:
+	@echo "NixOS Dotfiles - Available Commands"
+	@echo ""
+	@echo "  make switch      - Build and switch to new configuration"
+	@echo "  make test        - Build and test configuration (doesn't activate)"
+	@echo "  make build       - Build configuration without activating"
+	@echo "  make update      - Update flake.lock dependencies"
+	@echo "  make clean       - Clean old generations"
+	@echo "  make check       - Check flake and run basic validation"
+	@echo "  make fmt         - Format all Nix files"
+	@echo ""
+
+# Apply configuration
+switch:
+	sudo nixos-rebuild switch --flake .#nixos-btw
+
+# Test configuration without switching
+test:
+	sudo nixos-rebuild test --flake .#nixos-btw
+
+# Build configuration
+build:
+	sudo nixos-rebuild build --flake .#nixos-btw
+
+# Update flake dependencies
+update:
+	nix flake update
+	@echo "Dependencies updated. Run 'make switch' to apply."
+
+# Clean old generations (keeps last 3)
+clean:
+	@echo "Cleaning old system generations..."
+	sudo nix-collect-garbage --delete-older-than 7d
+	@echo "Done!"
+
+# Validate flake
+check:
+	nix flake check
+	@echo "Flake validation passed!"
+
+# Format Nix files
+fmt:
+	nixpkgs-fmt flake.nix
+	nixpkgs-fmt modules/**/*.nix
+	nixpkgs-fmt hosts/**/*.nix
+	@echo "All Nix files formatted!"
diff --git a/README.md b/README.md
index 56e3012..297ad45 100644
--- a/README.md
+++ b/README.md
@@ -4,6 +4,54 @@
 
 Welcome to my NixOS configuration! This is my personal setup running on a Dell Latitude 7490, featuring a sleek Qtile window manager with a Tokyo Night theme aesthetic. Built for coding, gaming, and general tech tinkering.
 
+## 📚 Documentation
+
+New to this repo? Start here:
+
+- **[⚡ Quick Start Guide](docs/QUICK_START.md)** - Get up and running in minutes
+- **[🏗️ Architecture Overview](docs/ARCHITECTURE.md)** - Understand how everything fits together
+- **[📦 Module Guide](docs/MODULE_GUIDE.md)** - Deep dive into each configuration module
+
+## 📂 Repository Structure
+
+```
+nixos-dotfiles/
+├── flake.nix              # Main flake configuration
+├── flake.lock             # Dependency lock file
+│
+├── hosts/                 # Host-specific configurations
+│   └── nixos-btw/        # This machine's config
+│       ├── default.nix          # Entry point
+│       ├── configuration.nix    # Host-specific settings
+│       ├── hardware-configuration.nix
+│       └── home.nix             # Home Manager config
+│
+├── modules/               # Reusable configuration modules
+│   ├── nixos/            # System-level (requires sudo)
+│   │   ├── core.nix            # Boot, networking, users
+│   │   ├── packages.nix        # System packages & fonts
+│   │   ├── services.nix        # System services
+│   │   └── wallpapers.nix      # Custom wallpapers
+│   │
+│   └── home-manager/     # User-level (no sudo)
+│       ├── apps.nix            # User packages
+│       ├── git.nix             # Git configuration
+│       ├── shell.nix           # Bash configuration
+│       └── devshell-scripts.nix # Dev environment scripts
+│
+├── config/                # Application dotfiles
+│   ├── nvim/             # Neovim configuration
+│   ├── qtile/            # Qtile WM configuration
+│   ├── rofi/             # Rofi launcher
+│   ├── picom/            # Compositor
+│   └── kitty/            # Terminal emulator
+│
+└── docs/                  # Documentation
+    ├── ARCHITECTURE.md         # System architecture
+    ├── QUICK_START.md          # Installation guide
+    └── MODULE_GUIDE.md         # Module documentation
+```
+
 ## 🎨 The Setup
 
 **OS:** NixOS 25.05 (Stable)  
@@ -49,30 +97,30 @@ Welcome to my NixOS configuration! This is my personal setup running on a Dell L
 
 ## 🎯 Quick Start
 
-### Prerequisites
-- A working NixOS installation
-- Git installed
-- Basic understanding of Nix flakes
+### For First-Time Users
 
-### Installation
+1. **Read the documentation first:**
+   - Start with [Quick Start Guide](docs/QUICK_START.md)
+   - Understand the [Architecture](docs/ARCHITECTURE.md)
+   - Review [Module Guide](docs/MODULE_GUIDE.md) for customization
 
-1. **Clone the repository:**
+2. **Clone and customize:**
 ```bash
-git clone https://github.com/YourUsername/nixos-dotfiles ~/nixos-dotfiles
+git clone https://github.com/BalrajSinghGidda/nixos-dotfiles ~/nixos-dotfiles
 cd ~/nixos-dotfiles
 ```
 
-2. **Review and customize:**
-   - Edit `configuration.nix` for system-level changes
-   - Edit `home.nix` for user-level configurations
-   - Modify configs in the `config/` directory as needed
+3. **Important: Update for your system:**
+   - Copy your hardware config: `sudo cp /etc/nixos/hardware-configuration.nix hosts/nixos-btw/`
+   - Update username in `hosts/nixos-btw/home.nix` and `modules/nixos/core.nix`
+   - Update Git info in `modules/home-manager/git.nix`
 
-3. **Apply the configuration:**
+4. **Apply the configuration:**
 ```bash
 sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
 ```
 
-4. **Enjoy your new setup!** 🎉
+See the [Quick Start Guide](docs/QUICK_START.md) for detailed instructions!
 
 ## 🔥 Custom Aliases
 
@@ -164,6 +212,30 @@ which intelephense
 ### Home Manager conflicts?
 Home Manager creates backups with `.backup` extension. Check those files if configs aren't applying.
 
+## 🛠️ Makefile Commands
+
+This repo includes a Makefile for common tasks:
+
+```bash
+make switch   # Apply configuration
+make test     # Test without switching
+make build    # Build without activating
+make update   # Update dependencies
+make clean    # Remove old generations
+make check    # Validate flake
+make fmt      # Format Nix files
+```
+
+## 🤝 Contributing
+
+Want to improve this configuration? Check out [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines!
+
+Quick tips:
+- Fork and customize for your own use
+- Open issues for bugs or questions
+- Submit PRs for improvements
+- Keep changes focused and well-documented
+
 ## 📚 Resources
 
 - [NixOS Manual](https://nixos.org/manual/nixos/stable/)
diff --git a/config/README.md b/config/README.md
new file mode 100644
index 0000000..ad38dcd
--- /dev/null
+++ b/config/README.md
@@ -0,0 +1,42 @@
+# Application Configurations
+
+This directory contains dotfiles for various applications, managed by Home Manager.
+
+## Applications
+
+- **nvim/** - Neovim configuration
+- **qtile/** - Qtile window manager configuration
+- **rofi/** - Rofi launcher theme
+- **picom/** - Picom compositor settings
+- **kitty/** - Kitty terminal emulator configuration
+
+## How It Works
+
+These configurations are symlinked to `~/.config/` by Home Manager.
+
+The linking is configured in `hosts/nixos-btw/home.nix`:
+
+```nix
+xdg.configFile."nvim".source = ../../config/nvim;
+xdg.configFile."qtile".source = ../../config/qtile;
+# etc...
+```
+
+## Making Changes
+
+1. Edit files in this directory directly
+2. For most applications, changes take effect immediately or on restart
+3. For some applications, you may need to rebuild:
+   ```bash
+   nrs
+   ```
+
+## Adding New Application Config
+
+1. Create a new directory: `config/myapp/`
+2. Add your configuration files
+3. Link it in `hosts/nixos-btw/home.nix`:
+   ```nix
+   xdg.configFile."myapp".source = ../../config/myapp;
+   ```
+4. Rebuild the system
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..ca96405
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,164 @@
+# 🏗️ Architecture Overview
+
+This document explains how the NixOS dotfiles repository is organized and how the different components work together.
+
+## 📂 Directory Structure
+
+```
+nixos-dotfiles/
+├── flake.nix                 # Main entry point - defines inputs and system configuration
+├── flake.lock                # Locked versions of dependencies
+│
+├── hosts/                    # Host-specific configurations
+│   └── nixos-btw/           # Configuration for the "nixos-btw" machine
+│       ├── default.nix      # Host entry point - imports all host configs
+│       ├── configuration.nix # Host-specific system settings (currently minimal)
+│       ├── hardware-configuration.nix # Hardware-specific settings (auto-generated)
+│       └── home.nix         # Home Manager configuration for this host
+│
+├── modules/                  # Reusable configuration modules
+│   ├── nixos/               # System-level NixOS modules
+│   │   ├── default.nix      # Imports all NixOS modules
+│   │   ├── core.nix         # Core system settings (boot, networking, users)
+│   │   ├── packages.nix     # System-wide packages and fonts
+│   │   ├── services.nix     # System services (X11, audio, bluetooth, etc.)
+│   │   ├── wallpapers.nix   # Custom wallpapers package
+│   │   └── wallpapers/      # Wallpaper files
+│   │
+│   └── home-manager/        # User-level Home Manager modules
+│       ├── default.nix      # Imports all Home Manager modules
+│       ├── apps.nix         # User applications and tools
+│       ├── git.nix          # Git and GitHub CLI configuration
+│       ├── shell.nix        # Bash shell configuration
+│       ├── devshell-scripts.nix  # Custom development shell scripts
+│       └── devshell-scripts/     # Shell script implementations
+│
+└── config/                   # Application dotfiles (managed via Home Manager)
+    ├── nvim/                # Neovim configuration
+    ├── qtile/               # Qtile window manager configuration
+    ├── rofi/                # Rofi launcher configuration
+    ├── picom/               # Picom compositor configuration
+    └── kitty/               # Kitty terminal configuration
+```
+
+## 🔄 Configuration Flow
+
+### System Build Process
+
+1. **Entry Point**: `flake.nix`
+   - Defines NixOS and Home Manager as inputs
+   - Creates `nixosConfigurations.nixos-btw` configuration
+
+2. **Host Configuration**: `hosts/nixos-btw/default.nix`
+   - Imports hardware configuration
+   - Imports shared NixOS modules from `modules/nixos/`
+
+3. **NixOS Modules**: `modules/nixos/`
+   - **core.nix**: Boot loader, networking, timezone, users
+   - **packages.nix**: System packages, fonts
+   - **services.nix**: X11, audio (PipeWire), Bluetooth, Docker, etc.
+
+4. **Home Manager**: Integrated in `flake.nix`
+   - User configuration from `hosts/nixos-btw/home.nix`
+   - Imports modules from `modules/home-manager/`
+
+5. **Home Manager Modules**: `modules/home-manager/`
+   - **apps.nix**: User packages and CLI tools
+   - **git.nix**: Git and GitHub configuration
+   - **shell.nix**: Bash prompt, aliases, environment variables
+
+6. **Dotfiles**: Managed in `hosts/nixos-btw/home.nix`
+   - Configs symlinked from `config/` to `~/.config/`
+
+## 🎯 Design Principles
+
+### Modularity
+- Each module handles a specific domain (core system, packages, services, etc.)
+- Modules are reusable across different hosts
+- Easy to enable/disable features by commenting imports
+
+### Separation of Concerns
+- **System-level** (modules/nixos/): Requires root, affects all users
+- **User-level** (modules/home-manager/): Per-user configuration
+- **Host-specific** (hosts/): Machine-specific settings
+- **Application configs** (config/): Dotfiles for specific programs
+
+### Declarative Configuration
+- Everything is defined in Nix expressions
+- Reproducible across machines
+- Version-controlled and atomic updates
+
+## 🔌 Key Components
+
+### Flakes
+This configuration uses Nix flakes for:
+- Dependency management (pinned versions in `flake.lock`)
+- Reproducible builds
+- Easy sharing and composition
+
+### Home Manager
+Manages user environment:
+- User packages
+- Dotfiles and configurations
+- Shell environment
+- Program-specific settings
+
+### Custom Packages
+- **wallpapers**: Custom package bundling wallpaper images
+- **devshell-scripts**: Custom scripts for creating development environments
+
+## 🚀 Adding New Features
+
+### Add a System Package
+Edit `modules/nixos/packages.nix`:
+```nix
+environment.systemPackages = with pkgs; [
+  # ... existing packages
+  your-new-package
+];
+```
+
+### Add a User Package
+Edit `modules/home-manager/apps.nix`:
+```nix
+home.packages = with pkgs; [
+  # ... existing packages
+  your-new-package
+];
+```
+
+### Add a System Service
+Edit `modules/nixos/services.nix`:
+```nix
+services.your-service = {
+  enable = true;
+  # ... configuration
+};
+```
+
+### Add a New Module
+1. Create `modules/nixos/your-module.nix` or `modules/home-manager/your-module.nix`
+2. Add to respective `default.nix`:
+```nix
+imports = [
+  # ... existing imports
+  ./your-module.nix
+];
+```
+
+## 🔍 Understanding the Build
+
+When you run `sudo nixos-rebuild switch --flake .#nixos-btw`:
+
+1. Nix reads `flake.nix`
+2. Looks up `nixosConfigurations.nixos-btw`
+3. Evaluates all imported modules
+4. Builds the system closure
+5. Activates the new configuration
+6. Home Manager runs and sets up user environment
+
+## 📚 Further Reading
+
+- [NixOS Manual](https://nixos.org/manual/nixos/stable/)
+- [Home Manager Manual](https://nix-community.github.io/home-manager/)
+- [Nix Flakes](https://nixos.wiki/wiki/Flakes)
diff --git a/docs/MODULE_GUIDE.md b/docs/MODULE_GUIDE.md
new file mode 100644
index 0000000..a94e1d5
--- /dev/null
+++ b/docs/MODULE_GUIDE.md
@@ -0,0 +1,617 @@
+# 📦 Module Guide
+
+This guide explains each module in detail and how to customize them.
+
+## 📑 Table of Contents
+
+- [NixOS Modules](#nixos-modules)
+  - [core.nix](#corenix)
+  - [packages.nix](#packagesnix)
+  - [services.nix](#servicesnix)
+  - [wallpapers.nix](#wallpapersnix)
+- [Home Manager Modules](#home-manager-modules)
+  - [apps.nix](#appsnix)
+  - [git.nix](#gitnix)
+  - [shell.nix](#shellnix)
+  - [devshell-scripts.nix](#devshell-scriptsnix)
+
+---
+
+## NixOS Modules
+
+Located in `modules/nixos/` - These require `sudo` to modify and affect the entire system.
+
+### core.nix
+
+**Purpose**: Essential system configuration - boot, networking, users, and kernel modules.
+
+**What it does**:
+- Configures systemd-boot bootloader
+- Sets hostname and enables NetworkManager
+- Configures timezone
+- Creates user accounts
+- Enables Nix flakes
+- Loads Dell-specific kernel modules
+
+**Common customizations**:
+
+```nix
+# Change hostname
+networking.hostName = "my-nixos-machine";
+
+# Change timezone
+time.timeZone = "America/New_York";
+
+# Add a new user
+users.users.newuser = {
+  isNormalUser = true;
+  extraGroups = [ "wheel" "networkmanager" ];
+  packages = with pkgs; [ firefox chromium ];
+};
+
+# Add kernel modules
+boot.kernelModules = [
+  # ... existing modules
+  "your-module"
+];
+```
+
+**Dependencies**: None
+
+---
+
+### packages.nix
+
+**Purpose**: System-wide packages and fonts available to all users.
+
+**What it does**:
+- Installs essential CLI tools (git, vim, neovim, etc.)
+- Installs GUI applications (kitty, rofi, libreoffice)
+- Installs development tools (direnv, lazygit, etc.)
+- Configures system fonts (Nerd Fonts, etc.)
+- Includes custom wallpapers package
+
+**Package categories**:
+
+```nix
+# Essential tools
+vim wget git gh
+
+# Terminal & multiplexers
+kitty zellij tmux
+
+# Window manager & desktop
+picom rofi xwallpaper feh
+
+# Development
+direnv lazygit redis
+
+# Utilities
+brightnessctl pamixer blueman dunst maim slop
+
+# Productivity
+libreoffice
+
+# System monitoring
+nitch
+```
+
+**Common customizations**:
+
+```nix
+# Add new packages
+environment.systemPackages = with pkgs; [
+  # ... existing packages
+  vscode
+  discord
+  spotify
+];
+
+# Add new fonts
+fonts.packages = with pkgs; [
+  # ... existing fonts
+  nerd-fonts.fira-code
+  google-fonts
+];
+
+# Remove packages you don't need
+# Just comment out or delete the line
+```
+
+**Dependencies**: `wallpapers.nix`
+
+---
+
+### services.nix
+
+**Purpose**: System services and daemons - X11, audio, bluetooth, Docker, etc.
+
+**What it does**:
+- Enables X11 window system
+- Configures Qtile window manager
+- Sets up PipeWire (audio server)
+- Enables PulseAudio compatibility
+- Configures Bluetooth with experimental features
+- Sets up rootless Docker
+- Enables Flatpak support
+- Configures Tailscale VPN
+
+**Service breakdown**:
+
+```nix
+# Display server
+services.xserver = {
+  enable = true;
+  xkb.layout = "us";
+  windowManager.qtile = {
+    enable = true;
+    backend = "x11";
+  };
+};
+
+# Audio stack
+services.pipewire = {
+  enable = true;
+  alsa.enable = true;
+  pulse.enable = true;
+};
+
+# Bluetooth
+services.blueman.enable = true;
+hardware.bluetooth = {
+  enable = true;
+  powerOnBoot = true;
+  settings.General.Experimental = true;
+};
+
+# Container runtime
+virtualisation.docker = {
+  enable = true;
+  rootless = {
+    enable = true;
+    setSocketVariable = true;
+  };
+};
+
+# VPN
+services.tailscale.enable = true;
+
+# Package management
+services.flatpak.enable = true;
+```
+
+**Common customizations**:
+
+```nix
+# Switch to Wayland
+services.xserver.enable = false;  # Disable X11
+programs.wayland.enable = true;
+
+# Change window manager to i3
+services.xserver.windowManager.i3.enable = true;
+services.xserver.windowManager.qtile.enable = false;
+
+# Disable Bluetooth
+hardware.bluetooth.enable = false;
+services.blueman.enable = false;
+
+# Enable printing
+services.printing.enable = true;
+
+# Enable SSH server
+services.openssh = {
+  enable = true;
+  settings.PermitRootLogin = "no";
+};
+
+# Add more audio codecs
+services.pipewire.extraConfig.pipewire."92-low-latency" = {
+  context.properties = {
+    default.clock.rate = 48000;
+    default.clock.quantum = 32;
+  };
+};
+```
+
+**Dependencies**: None
+
+---
+
+### wallpapers.nix
+
+**Purpose**: Custom package that bundles wallpaper images.
+
+**What it does**:
+- Creates a derivation containing wallpaper files
+- Installs wallpapers to the Nix store
+- Makes them available systemwide
+
+**Structure**:
+```nix
+pkgs.stdenv.mkDerivation {
+  name = "wallpapers";
+  src = ./wallpapers/Pictures;
+  installPhase = ''
+    mkdir -p $out/share/wallpapers
+    cp -r $src/* $out/share/wallpapers/
+  '';
+}
+```
+
+**Usage**:
+```bash
+# Wallpapers are located at:
+/nix/store/.../share/wallpapers/
+
+# Set with feh
+feh --bg-scale /nix/store/.../share/wallpapers/nix.png
+
+# Or use xwallpaper
+xwallpaper --zoom /path/to/wallpaper.png
+```
+
+**Adding wallpapers**:
+1. Place images in `modules/nixos/wallpapers/Pictures/`
+2. Rebuild system
+3. Wallpapers are now in the Nix store
+
+**Dependencies**: None (but used by `packages.nix`)
+
+---
+
+## Home Manager Modules
+
+Located in `modules/home-manager/` - User-level configuration, no sudo required.
+
+### apps.nix
+
+**Purpose**: User packages and command-line tools.
+
+**What it does**:
+- Installs user-specific packages
+- Configures Gemini CLI (AI assistant)
+- Includes custom devshell scripts
+
+**Package categories**:
+
+```nix
+home.packages = with pkgs; [
+  # Code tools
+  ripgrep nil nixpkgs-fmt nodejs gcc
+
+  # File management
+  yazi eza zoxide
+
+  # Package management
+  flatpak
+
+  # Development
+  python313Packages.euporie
+
+  # Custom scripts
+  devshell-scripts
+];
+```
+
+**Gemini CLI configuration**:
+```nix
+programs.gemini-cli = {
+  enable = true;
+  settings = {
+    theme = "Default";
+    preferredEditor = "nvim";
+    autoAccept = true;
+  };
+  defaultModel = "gemini-2.5-pro";
+};
+```
+
+**Common customizations**:
+
+```nix
+# Add more packages
+home.packages = with pkgs; [
+  # ... existing packages
+  neofetch
+  htop
+  btop
+  
+  # Language-specific tools
+  rustc
+  cargo
+  go
+  python311
+];
+
+# Configure Gemini CLI
+programs.gemini-cli.settings = {
+  theme = "Dark";
+  defaultModel = "gemini-1.5-pro";
+};
+
+# Disable Gemini CLI
+programs.gemini-cli.enable = false;
+```
+
+**Dependencies**: `devshell-scripts.nix`
+
+---
+
+### git.nix
+
+**Purpose**: Git and GitHub CLI configuration.
+
+**What it does**:
+- Configures Git user identity
+- Enables GitHub CLI (gh)
+- Sets up git credential helper
+- Configures gh preferences
+
+**Current configuration**:
+```nix
+programs.git = {
+  enable = true;
+  settings = {
+    user.name = "BalrajSinghGidda";
+    user.email = "anonystargamerz@gmail.com";
+  };
+};
+
+programs.gh = {
+  enable = true;
+  gitCredentialHelper.enable = true;
+  settings = {
+    git_protocol = "https";
+    prompt = "enable";
+    editor = "nvim";
+  };
+};
+```
+
+**Common customizations**:
+
+```nix
+# Update user info (REQUIRED for your setup!)
+programs.git.settings = {
+  user.name = "YourUsername";
+  user.email = "your-email@example.com";
+};
+
+# Add Git aliases
+programs.git.settings.alias = {
+  st = "status";
+  co = "checkout";
+  br = "branch";
+  ci = "commit";
+  unstage = "reset HEAD --";
+};
+
+# Configure default branch
+programs.git.settings.init.defaultBranch = "main";
+
+# Add signing
+programs.git.settings.commit.gpgsign = true;
+programs.git.settings.user.signingkey = "YOUR_GPG_KEY";
+
+# Use SSH for GitHub
+programs.gh.settings.git_protocol = "ssh";
+```
+
+**Dependencies**: None
+
+---
+
+### shell.nix
+
+**Purpose**: Bash shell environment - prompt, aliases, environment variables.
+
+**What it does**:
+- Configures Bash with completion
+- Sets custom PS1 prompt
+- Defines useful aliases
+- Configures environment variables
+- Integrates direnv and zoxide
+- Shows nitch on startup
+
+**Shell aliases**:
+```nix
+shellAliases = {
+  nc = "nvim ~/nixos-dotfiles/.";
+  btw = "echo I use NixOS, btw";
+  nrs = "sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw";
+  edit-config = "nvim ~/nixos-dotfiles/configuration.nix";
+  edit-home-config = "nvim ~/nixos-dotfiles/home.nix";
+  ls = "eza --long -ahF --no-user --no-permissions --git --icons=always --color=always --grid";
+  cd = "z";
+  bm = "bashmount";
+};
+```
+
+**Custom prompt**:
+- Cyan username@hostname
+- Green current directory
+- Light blue prompt symbol
+
+**Common customizations**:
+
+```nix
+# Add more aliases
+shellAliases = {
+  # ... existing aliases
+  ll = "ls -la";
+  ".." = "cd ..";
+  gs = "git status";
+  gp = "git push";
+  gl = "git pull";
+  nv = "nvim";
+  update = "nix flake update ~/nixos-dotfiles && nrs";
+};
+
+# Customize prompt
+bashrcExtra = ''
+  # Starship prompt (alternative)
+  eval "$(starship init bash)"
+  
+  # Or custom prompt
+  export PS1="\[\e[1;32m\]\u@\h \[\e[1;34m\]\w \[\e[1;31m\]\$ \[\e[0m\]"
+'';
+
+# Add environment variables
+bashrcExtra = ''
+  export EDITOR="nvim"
+  export VISUAL="nvim"
+  export BROWSER="firefox"
+  export PATH="$HOME/.local/bin:$PATH"
+'';
+
+# Remove nitch startup
+# Just delete or comment out the 'nitch' line in bashrcExtra
+```
+
+**Dependencies**: None (uses eza and zoxide from `apps.nix`)
+
+---
+
+### devshell-scripts.nix
+
+**Purpose**: Custom scripts for creating development environments.
+
+**What it does**:
+- Packages custom shell scripts
+- Makes them available in PATH
+- Provides commands for setting up dev environments
+
+**Available scripts**:
+- `make-py-devshell` - Python development environment
+- `make-cpp-devshell` - C++ development environment
+- `make-go-devshell` - Go development environment
+- `make-java-devshell` - Java development environment
+- `make-ruby-devshell` - Ruby development environment
+- `make-rust-devshell` - Rust development environment
+
+**Structure**:
+```nix
+pkgs.stdenv.mkDerivation {
+  name = "devshell-scripts";
+  src = ./devshell-scripts;
+  installPhase = ''
+    mkdir -p $out/bin
+    cp -r $src/* $out/bin/
+    chmod +x $out/bin/*
+  '';
+}
+```
+
+**Usage**:
+```bash
+# Create a Python project with dev environment
+make-py-devshell my-python-project
+cd my-python-project
+direnv allow
+
+# Create a Rust project
+make-rust-devshell my-rust-project
+```
+
+**Adding new scripts**:
+1. Create script in `modules/home-manager/devshell-scripts/`
+2. Make it executable
+3. Rebuild Home Manager
+
+**Dependencies**: None (but scripts use direnv from `apps.nix`)
+
+---
+
+## 🔗 Module Dependencies
+
+```
+flake.nix
+  ├── hosts/nixos-btw/default.nix
+  │   ├── configuration.nix
+  │   ├── hardware-configuration.nix
+  │   └── modules/nixos/
+  │       ├── core.nix
+  │       ├── packages.nix (uses wallpapers.nix)
+  │       ├── services.nix
+  │       └── wallpapers.nix
+  │
+  └── home-manager
+      ├── hosts/nixos-btw/home.nix
+      └── modules/home-manager/
+          ├── apps.nix (uses devshell-scripts.nix)
+          ├── git.nix
+          ├── shell.nix
+          └── devshell-scripts.nix
+```
+
+## 🎯 Best Practices
+
+1. **Keep modules focused**: Each module should handle one domain
+2. **Comment your changes**: Future you will thank present you
+3. **Test incrementally**: Make small changes and test frequently
+4. **Use meaningful names**: If you split a module, name it descriptively
+5. **Document customizations**: Add comments explaining why you made changes
+
+## 🚀 Creating New Modules
+
+### NixOS Module Template
+
+```nix
+# modules/nixos/my-module.nix
+{ config, pkgs, ... }:
+
+{
+  # Your system-level configuration here
+  environment.systemPackages = with pkgs; [
+    # packages
+  ];
+  
+  services.my-service = {
+    enable = true;
+    # configuration
+  };
+}
+```
+
+Then add to `modules/nixos/default.nix`:
+```nix
+{
+  imports = [
+    # ... existing imports
+    ./my-module.nix
+  ];
+}
+```
+
+### Home Manager Module Template
+
+```nix
+# modules/home-manager/my-module.nix
+{ config, pkgs, ... }:
+
+{
+  # Your user-level configuration here
+  home.packages = with pkgs; [
+    # packages
+  ];
+  
+  programs.my-program = {
+    enable = true;
+    # configuration
+  };
+}
+```
+
+Then add to `modules/home-manager/default.nix`:
+```nix
+{
+  imports = [
+    # ... existing imports
+    ./my-module.nix
+  ];
+}
+```
+
+---
+
+Happy customizing! 🎉
diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md
new file mode 100644
index 0000000..a51d3e8
--- /dev/null
+++ b/docs/QUICK_START.md
@@ -0,0 +1,264 @@
+# ⚡ Quick Start Guide
+
+Get up and running with this NixOS configuration in minutes!
+
+## 🎯 Prerequisites
+
+Before you begin, ensure you have:
+
+- ✅ NixOS installed (tested on 25.11)
+- ✅ Git installed
+- ✅ Basic familiarity with terminal commands
+- ✅ Admin (sudo) access
+
+## 📥 Installation Steps
+
+### 1. Backup Your Current Configuration
+
+```bash
+# Backup your current NixOS configuration
+sudo cp -r /etc/nixos /etc/nixos.backup
+
+# Backup your home directory configs (optional but recommended)
+cp -r ~/.config ~/.config.backup
+```
+
+### 2. Clone This Repository
+
+```bash
+# Clone to your home directory
+git clone https://github.com/BalrajSinghGidda/nixos-dotfiles ~/nixos-dotfiles
+cd ~/nixos-dotfiles
+```
+
+### 3. Review and Customize
+
+**Important**: Before applying, customize these files for your system:
+
+#### Edit Host-Specific Settings
+
+```bash
+# Copy your hardware configuration
+sudo cp /etc/nixos/hardware-configuration.nix ~/nixos-dotfiles/hosts/nixos-btw/
+
+# Edit host settings if needed
+nvim hosts/nixos-btw/configuration.nix
+```
+
+#### Update User Information
+
+Edit `modules/home-manager/git.nix`:
+```nix
+user.name = "YourGitHubUsername";
+user.email = "your-email@example.com";
+```
+
+Edit `modules/nixos/core.nix`:
+```nix
+users.users.balraj = {  # Change 'balraj' to your username
+  isNormalUser = true;
+  extraGroups = [ "wheel" "networking" ];
+};
+```
+
+Edit `hosts/nixos-btw/home.nix`:
+```nix
+home.username = "your-username";
+home.homeDirectory = "/home/your-username";
+```
+
+#### Update Hostname (Optional)
+
+Edit `modules/nixos/core.nix`:
+```nix
+networking.hostName = "your-hostname";  # Change from "nixos-btw"
+```
+
+If you change the hostname, also update `flake.nix`:
+```nix
+nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
+  # ...
+};
+```
+
+### 4. Test the Configuration
+
+```bash
+# Dry-run to check for errors (doesn't apply changes)
+sudo nixos-rebuild dry-build --flake ~/nixos-dotfiles/#nixos-btw
+```
+
+### 5. Apply the Configuration
+
+```bash
+# Apply the configuration
+sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
+```
+
+This will:
+- Install all system packages
+- Configure system services
+- Set up Home Manager
+- Link dotfiles to ~/.config
+
+### 6. Reboot (Recommended)
+
+```bash
+sudo reboot
+```
+
+## 🎨 First Login
+
+After reboot, you should see:
+
+1. **Login screen** - Log in with your user credentials
+2. **Qtile WM** - Tiled window manager with Tokyo Night theme
+3. **Terminal** - Opens Kitty with custom theme
+4. **System info** - `nitch` displays on shell startup
+
+## 🔧 Post-Installation
+
+### Test Key Features
+
+```bash
+# Test Neovim
+nvim
+
+# Test file manager
+yazi
+
+# Test launcher (press: Mod + p in Qtile)
+# Rofi should appear
+
+# Check Git configuration
+git config --list
+
+# Test development shell creation
+make-py-devshell my-project
+```
+
+### Verify Services
+
+```bash
+# Check PipeWire audio
+pactl info
+
+# Check Bluetooth
+bluetoothctl show
+
+# Check Docker (rootless)
+docker ps
+```
+
+## 📝 Making Changes
+
+### Update System Configuration
+
+```bash
+# Edit any .nix file
+nvim ~/nixos-dotfiles/modules/nixos/packages.nix
+
+# Apply changes
+sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
+```
+
+### Update User Configuration
+
+```bash
+# Edit home-manager files
+nvim ~/nixos-dotfiles/modules/home-manager/apps.nix
+
+# Apply changes (same command as system)
+sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
+```
+
+### Update Dotfiles
+
+```bash
+# Edit application configs
+nvim ~/nixos-dotfiles/config/kitty/kitty.conf
+
+# Changes apply immediately (or restart the application)
+```
+
+## 🚀 Useful Aliases
+
+This configuration includes helpful aliases:
+
+```bash
+nc          # Quick edit nixos-dotfiles in Neovim
+nrs         # Rebuild NixOS system
+btw         # Echo "I use NixOS, btw"
+ls          # Enhanced ls with icons and git status
+cd          # Smart directory navigation with zoxide
+```
+
+## ❓ Common Issues
+
+### Issue: "error: flake not found"
+
+**Solution**: Make sure you're in the correct directory or use full path:
+```bash
+sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
+```
+
+### Issue: Home Manager file conflicts
+
+**Solution**: Home Manager creates backups. Check `*.backup` files:
+```bash
+ls ~/.config/*.backup
+```
+
+Remove or merge conflicts, then rebuild.
+
+### Issue: Graphics/display issues
+
+**Solution**: Your hardware config may need adjustment:
+```bash
+# Copy your original hardware config
+sudo cp /etc/nixos.backup/hardware-configuration.nix ~/nixos-dotfiles/hosts/nixos-btw/
+sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
+```
+
+### Issue: Permission denied for Docker
+
+**Solution**: Add yourself to docker group (already in services.nix):
+```bash
+# Re-login or run:
+newgrp docker
+```
+
+## 🔄 Rolling Back
+
+If something goes wrong:
+
+```bash
+# List generations
+sudo nix-env --list-generations --profile /nix/var/nix/profiles/system
+
+# Rollback to previous generation
+sudo nixos-rebuild switch --rollback
+
+# Or boot into previous generation from bootloader
+sudo reboot
+# Select older generation from systemd-boot menu
+```
+
+## 📚 Next Steps
+
+- Read [ARCHITECTURE.md](./ARCHITECTURE.md) to understand the structure
+- Check [MODULE_GUIDE.md](./MODULE_GUIDE.md) for customization details
+- Explore individual configs in `config/` directories
+- Join the NixOS community: [Discourse](https://discourse.nixos.org/), [Reddit](https://reddit.com/r/nixos)
+
+## 💡 Tips
+
+1. **Keep it in Git**: Always commit changes before rebuilding
+2. **Test before switching**: Use `nixos-rebuild test` for temporary changes
+3. **Update regularly**: Run `nix flake update` to update dependencies
+4. **Read error messages**: Nix errors are detailed and usually helpful
+5. **Start small**: Make incremental changes and test frequently
+
+---
+
+🎉 **Congratulations!** You're now running a fully declarative NixOS setup!
diff --git a/flake.nix b/flake.nix
index cb05e4b..91bed97 100644
--- a/flake.nix
+++ b/flake.nix
@@ -1,25 +1,39 @@
 {
   description = "NixOS on Dell Latitude 7490";
 
+  # Flake inputs - dependencies for this configuration
   inputs = {
+    # NixOS 25.11 stable channel
     nixpkgs.url = "nixpkgs/nixos-25.11";
+    
+    # Home Manager for user-level configuration management
     home-manager = {
       url = "github:nix-community/home-manager/release-25.11";
+      # Ensure Home Manager uses the same nixpkgs as system
       inputs.nixpkgs.follows = "nixpkgs";
     };
   };
 
+  # Flake outputs - what this flake produces
   outputs = { self, nixpkgs, home-manager, ... }: {
+    # System configuration for the "nixos-btw" host
     nixosConfigurations.nixos-btw = nixpkgs.lib.nixosSystem {
       system = "x86_64-linux";
       modules = [
+        # Import host-specific configuration
         ./hosts/nixos-btw
+        
+        # Enable Home Manager as a NixOS module
         home-manager.nixosModules.home-manager
         {
           home-manager = {
+            # Use system-level pkgs for Home Manager
             useGlobalPkgs = true;
+            # Install packages to /etc/profiles instead of ~/.nix-profile
             useUserPackages = true;
+            # Import Home Manager configuration for user 'balraj'
             users.balraj = import ./hosts/nixos-btw/home.nix;
+            # Backup existing files with .backup extension on conflicts
             backupFileExtension = "backup";
           };
         }
diff --git a/hosts/nixos-btw/configuration.nix b/hosts/nixos-btw/configuration.nix
deleted file mode 100644
index c421ecf..0000000
--- a/hosts/nixos-btw/configuration.nix
+++ /dev/null
@@ -1,6 +0,0 @@
-{
-  imports = [
-    ./hardware-configuration.nix
-    ../../modules/nixos
-  ];
-}
\ No newline at end of file
diff --git a/hosts/nixos-btw/default.nix b/hosts/nixos-btw/default.nix
index 6d7db49..5da7768 100644
--- a/hosts/nixos-btw/default.nix
+++ b/hosts/nixos-btw/default.nix
@@ -1,7 +1,11 @@
+# Host entry point for the "nixos-btw" machine
+# This file imports all system-level configuration for this host
 {
   imports = [
-    ./configuration.nix
+    # Hardware-specific configuration (auto-generated by nixos-generate-config)
     ./hardware-configuration.nix
+    
+    # Shared NixOS modules (core, packages, services)
     ../../modules/nixos
   ];
 }
diff --git a/hosts/nixos-btw/home.nix b/hosts/nixos-btw/home.nix
index 27f2b00..721a2be 100644
--- a/hosts/nixos-btw/home.nix
+++ b/hosts/nixos-btw/home.nix
@@ -1,16 +1,20 @@
 { config, pkgs, ... }:
 
 {
+  # Import Home Manager modules (apps, git, shell, etc.)
   imports = [
     ../../modules/home-manager
   ];
 
+  # User identity - CHANGE THESE for your system!
   home.username = "balraj";
   home.homeDirectory = "/home/balraj";
+  
+  # Home Manager state version - DON'T change this after initial setup
   home.stateVersion = "25.05";
 
-  # This is the idiomatic way to manage dotfiles in Home Manager.
-  # It will copy the files to the Nix store and then link them to the correct location in ~/.config.
+  # Manage application dotfiles using XDG Base Directory specification
+  # These files are copied to the Nix store and symlinked to ~/.config/
   xdg.configFile."nvim".source = ../../config/nvim;
   xdg.configFile."qtile".source = ../../config/qtile;
   xdg.configFile."rofi".source = ../../config/rofi;
diff --git a/modules/home-manager/README.md b/modules/home-manager/README.md
new file mode 100644
index 0000000..38b1674
--- /dev/null
+++ b/modules/home-manager/README.md
@@ -0,0 +1,36 @@
+# Home Manager Modules
+
+User-level configuration modules (no `sudo` required).
+
+## Structure
+
+### Tool Categories
+- **cli-tools.nix** - Command-line utilities (ripgrep, yazi, eza, zoxide)
+- **gui-apps.nix** - GUI applications (flatpak)
+- **dev-tools.nix** - Development tools and programming languages
+
+### Programs
+- **programs/gemini-cli.nix** - Gemini AI CLI configuration
+
+### Core Configuration
+- **git.nix** - Git and GitHub CLI setup
+- **shell.nix** - Bash environment (prompt, aliases, environment)
+
+### Scripts
+- **devshell-scripts.nix** - Custom development environment creation scripts
+- **devshell-scripts/** - Script implementations
+
+## Making Changes
+
+After editing any module, rebuild:
+
+```bash
+sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
+```
+
+Or use the alias:
+```bash
+nrs
+```
+
+See [docs/MODULE_GUIDE.md](../../docs/MODULE_GUIDE.md) for detailed documentation.
diff --git a/modules/home-manager/apps.nix b/modules/home-manager/apps.nix
deleted file mode 100644
index 9b66f3a..0000000
--- a/modules/home-manager/apps.nix
+++ /dev/null
@@ -1,30 +0,0 @@
-{ pkgs, ... }:
-
-let
-  devshell-scripts = pkgs.callPackage ./devshell-scripts.nix {};
-in
-{
-  programs.gemini-cli = {
-    enable = true;
-    settings = {
-      "theme" = "Default";
-      "preferredEditor" = "nvim";
-      "autoAccept" = true;
-    };
-    defaultModel = "gemini-2.5-pro";
-  };
-
-  home.packages = with pkgs; [
-    ripgrep
-    nil
-    nixpkgs-fmt
-    nodejs
-    gcc
-    yazi
-    flatpak
-    eza
-    zoxide
-    python313Packages.euporie
-    devshell-scripts
-  ];
-}
\ No newline at end of file
diff --git a/modules/home-manager/apps.nix.backup b/modules/home-manager/apps.nix.backup
new file mode 100644
index 0000000..0385e1c
--- /dev/null
+++ b/modules/home-manager/apps.nix.backup
@@ -0,0 +1,46 @@
+{ pkgs, ... }:
+
+let
+  # Import custom devshell scripts package
+  devshell-scripts = pkgs.callPackage ./devshell-scripts.nix {};
+in
+{
+  # Gemini AI CLI tool configuration
+  programs.gemini-cli = {
+    enable = true;
+    settings = {
+      "theme" = "Default";
+      "preferredEditor" = "nvim";
+      "autoAccept" = true;
+    };
+    defaultModel = "gemini-2.5-pro";
+  };
+
+  # User packages (installed to user profile, not system-wide)
+  home.packages = with pkgs; [
+    # Code search and analysis
+    ripgrep         # Fast grep alternative (rg)
+    
+    # Nix development tools
+    nil             # Nix language server
+    nixpkgs-fmt     # Nix code formatter
+    
+    # Programming languages & compilers
+    nodejs          # JavaScript runtime
+    gcc             # C/C++ compiler
+    
+    # File management
+    yazi            # Terminal file manager
+    eza             # Modern ls replacement
+    zoxide          # Smart cd command
+    
+    # Package management
+    flatpak         # Universal package manager
+    
+    # Python packages
+    python313Packages.euporie  # Jupyter notebook terminal client
+    
+    # Custom scripts for creating development environments
+    devshell-scripts
+  ];
+}
\ No newline at end of file
diff --git a/modules/home-manager/cli-tools.nix b/modules/home-manager/cli-tools.nix
new file mode 100644
index 0000000..81eb1b7
--- /dev/null
+++ b/modules/home-manager/cli-tools.nix
@@ -0,0 +1,18 @@
+{ pkgs, ... }:
+
+{
+  # Command-line tools and utilities
+  home.packages = with pkgs; [
+    # Code search and analysis
+    ripgrep         # Fast grep alternative (rg)
+    
+    # File management
+    yazi            # Terminal file manager
+    eza             # Modern ls replacement
+    zoxide          # Smart cd command
+    
+    # Nix development tools
+    nil             # Nix language server
+    nixpkgs-fmt     # Nix code formatter
+  ];
+}
\ No newline at end of file
diff --git a/modules/home-manager/default.nix b/modules/home-manager/default.nix
index 8005cd0..43b4944 100644
--- a/modules/home-manager/default.nix
+++ b/modules/home-manager/default.nix
@@ -1,7 +1,17 @@
+# Home Manager module aggregator
+# This file imports all user-level configuration modules
 {
   imports = [
-    ./apps.nix
-    ./git.nix
-    ./shell.nix
+    # Tool categories
+    ./cli-tools.nix   # Command-line utilities
+    ./gui-apps.nix    # GUI applications
+    ./dev-tools.nix   # Development tools and languages
+    
+    # Program-specific configurations
+    ./programs/gemini-cli.nix  # Gemini AI CLI
+    
+    # Core configurations
+    ./git.nix    # Git and GitHub configuration
+    ./shell.nix  # Shell environment (bash)
   ];
 }
diff --git a/modules/home-manager/dev-tools.nix b/modules/home-manager/dev-tools.nix
new file mode 100644
index 0000000..6d3ce68
--- /dev/null
+++ b/modules/home-manager/dev-tools.nix
@@ -0,0 +1,20 @@
+{ pkgs, ... }:
+
+let
+  # Import custom devshell scripts package
+  devshell-scripts = pkgs.callPackage ./devshell-scripts.nix {};
+in
+{
+  # Development tools and programming languages
+  home.packages = with pkgs; [
+    # Programming languages & compilers
+    nodejs          # JavaScript runtime
+    gcc             # C/C++ compiler
+    
+    # Python packages
+    python313Packages.euporie  # Jupyter notebook terminal client
+    
+    # Custom scripts for creating development environments
+    devshell-scripts
+  ];
+}
\ No newline at end of file
diff --git a/modules/home-manager/git.nix b/modules/home-manager/git.nix
index bd1d5d7..cce631c 100644
--- a/modules/home-manager/git.nix
+++ b/modules/home-manager/git.nix
@@ -1,21 +1,23 @@
 { pkgs, ... }:
 
 {
+  # Git version control configuration
   programs.git = {
     enable = true;
-    settings = {
-      user.name = "BalrajSinghGidda";
-      user.email = "anonystargamerz@gmail.com";
-    };
+    # IMPORTANT: Change these to your own details!
+    userName = "BalrajSinghGidda";
+    userEmail = "anonystargamerz@gmail.com";
   };
 
+  # GitHub CLI configuration
   programs.gh = {
     enable = true;
+    # Use gh as git credential helper
     gitCredentialHelper.enable = true;
     settings = {
-      git_protocol = "https";
-      prompt = "enable";
-      editor = "nvim";
+      git_protocol = "https";  # Use HTTPS for git operations (change to "ssh" if you prefer)
+      prompt = "enabled";      # Enable interactive prompts
+      editor = "nvim";         # Default editor for gh commands
     };
   };
 }
\ No newline at end of file
diff --git a/modules/home-manager/gui-apps.nix b/modules/home-manager/gui-apps.nix
new file mode 100644
index 0000000..369c235
--- /dev/null
+++ b/modules/home-manager/gui-apps.nix
@@ -0,0 +1,9 @@
+{ pkgs, ... }:
+
+{
+  # GUI applications (managed by Home Manager)
+  home.packages = with pkgs; [
+    # Package management
+    flatpak         # Universal package manager
+  ];
+}
\ No newline at end of file
diff --git a/modules/home-manager/programs/gemini-cli.nix b/modules/home-manager/programs/gemini-cli.nix
new file mode 100644
index 0000000..cd7c668
--- /dev/null
+++ b/modules/home-manager/programs/gemini-cli.nix
@@ -0,0 +1,14 @@
+{ pkgs, ... }:
+
+{
+  # Gemini AI CLI tool configuration
+  programs.gemini-cli = {
+    enable = true;
+    settings = {
+      "theme" = "Default";
+      "preferredEditor" = "nvim";
+      "autoAccept" = true;
+    };
+    defaultModel = "gemini-2.5-pro";
+  };
+}
\ No newline at end of file
diff --git a/modules/home-manager/shell.nix b/modules/home-manager/shell.nix
index 3a57dfe..f57beec 100644
--- a/modules/home-manager/shell.nix
+++ b/modules/home-manager/shell.nix
@@ -1,29 +1,55 @@
 { pkgs, ... }:
 
 {
+  # Bash shell configuration
   programs.bash = {
     enable = true;
-    enableCompletion = true;
+    enableCompletion = true;  # Tab completion for commands
+    
+    # Custom shell aliases for convenience
     shellAliases = {
-      nc = "nvim ~/nixos-dotfiles/.";
-      btw = "echo I use NixOS, btw";
-      nrs = "sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw";
-      edit-config = "nvim ~/nixos-dotfiles/configuration.nix";
-      edit-home-config = "nvim ~/nixos-dotfiles/home.nix";
+      # NixOS management
+      nc = "nvim ~/nixos-dotfiles/.";  # Quick edit dotfiles
+      btw = "echo I use NixOS, btw";   # Because we have to let everyone know
+      nrs = "sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw";  # Rebuild system
+      
+      # Config editing shortcuts
+      edit-nixos = "nvim ~/nixos-dotfiles/modules/nixos/";
+      edit-home = "nvim ~/nixos-dotfiles/modules/home-manager/";
+      edit-host = "nvim ~/nixos-dotfiles/hosts/nixos-btw/";
+      
+      # Enhanced file operations
       ls = "eza --long -ahF --no-user --no-permissions --git --icons=always --color=always --grid";
-      cd = "z";
-      bm = "bashmount";
+      cd = "z";  # Use zoxide for smart directory jumping
+      
+      # Utilities
+      bm = "bashmount";  # Mount/unmount utility
     };
+    
+    # Don't save these commands in history
     historyIgnore = [
       "ls"
       "exit"
     ];
+    
+    # Additional bash configuration
     bashrcExtra = ''
+      # Custom prompt: cyan user@host, green directory, light blue prompt
       export PS1="\[\e[38;5;75m\]\u@\h \[\e[38;5;113m\]\w \[\e[38;5;189m\]\$ \[\e[0m\]"
+      
+      # Use Neovim as manpage viewer
       export MANPAGER="nvim +Man!"
+      
+      # Use fd for faster file searching in fzf
       export FZF_DEFAULT_COMMAND='fd --type f --hidden --follow'
+      
+      # Initialize direnv (per-directory environments)
       eval "$(direnv hook bash)"
+      
+      # Initialize zoxide (smart cd)
       eval "$(zoxide init bash)"
+      
+      # Show system info on shell startup
       nitch
     '';
   };
diff --git a/modules/nixos/README.md b/modules/nixos/README.md
new file mode 100644
index 0000000..4cf7338
--- /dev/null
+++ b/modules/nixos/README.md
@@ -0,0 +1,20 @@
+# NixOS Modules
+
+System-level configuration modules that require `sudo` to modify.
+
+## Modules
+
+- **core.nix** - Essential system settings (boot, networking, users, timezone)
+- **packages.nix** - System-wide packages and fonts
+- **services.nix** - System services (X11, audio, Bluetooth, Docker, etc.)
+- **wallpapers.nix** - Custom wallpapers package
+
+## Making Changes
+
+After editing any module, rebuild the system:
+
+```bash
+sudo nixos-rebuild switch --flake ~/nixos-dotfiles/#nixos-btw
+```
+
+See [docs/MODULE_GUIDE.md](../../docs/MODULE_GUIDE.md) for detailed documentation.
diff --git a/modules/nixos/core.nix b/modules/nixos/core.nix
index 87d8290..5288a09 100644
--- a/modules/nixos/core.nix
+++ b/modules/nixos/core.nix
@@ -1,39 +1,49 @@
 { pkgs, ... }:
 
 {
+  # Bootloader configuration
   boot.loader.systemd-boot.enable = true;
   boot.loader.efi.canTouchEfiVariables = true;
 
-  networking.hostName = "nixos-btw";
+  # Network configuration
+  networking.hostName = "nixos-btw";  # Change this for your machine
   networking.networkmanager.enable = true;
 
+  # Timezone and locale
   time.timeZone = "Asia/Kolkata";
 
+  # Allow unfree packages (needed for some proprietary software)
   nixpkgs.config.allowUnfree = true;
 
+  # Bash configuration
   programs.bash.completion.enable = true;
-  programs.bash.blesh.enable = true;
+  programs.bash.blesh.enable = true;  # Bash Line Editor SHell
 
+  # Firefox browser
   programs.firefox.enable = true;
 
+  # Dell-specific kernel modules for proper hardware support
   boot.kernelModules = [
-      "dell-wmi"
-      "dell-wmi-sysman"
-      "dell-smbios"
-      "dell-wmi-descriptor"
-      "video"
-      "sparse-keymap"
+      "dell-wmi"              # WMI driver for Dell laptops
+      "dell-wmi-sysman"       # System management
+      "dell-smbios"           # SMBIOS interface
+      "dell-wmi-descriptor"   # WMI descriptor
+      "video"                 # Video driver
+      "sparse-keymap"         # Sparse keymap support
   ];
 
+  # User account configuration - CHANGE 'balraj' to your username!
   users.users.balraj = {
     isNormalUser = true;
-    extraGroups = [ "wheel" "networking" ];
+    extraGroups = [ "wheel" "networking" ];  # wheel = sudo access
     packages = with pkgs; [
-      tree
+      tree  # Directory tree visualization
     ];
   };
 
+  # Enable Nix flakes and new nix command
   nix.settings.experimental-features = [ "nix-command" "flakes" ];
 
+  # NixOS state version - DON'T change after initial installation
   system.stateVersion = "25.11";
 }
diff --git a/modules/nixos/default.nix b/modules/nixos/default.nix
index d9226a3..ba1c359 100644
--- a/modules/nixos/default.nix
+++ b/modules/nixos/default.nix
@@ -1,7 +1,9 @@
+# NixOS module aggregator
+# This file imports all system-level configuration modules
 {
   imports = [
-    ./core.nix
-    ./packages.nix
-    ./services.nix
+    ./core.nix      # Core system settings (boot, networking, users)
+    ./packages.nix  # System packages and fonts
+    ./services.nix  # System services and daemons
   ];
 }
diff --git a/modules/nixos/packages.nix b/modules/nixos/packages.nix
index 0caaf6b..102ba04 100644
--- a/modules/nixos/packages.nix
+++ b/modules/nixos/packages.nix
@@ -1,54 +1,78 @@
 { pkgs, ... }:
 
 let
+  # Import custom wallpapers package
   wallpapers = (pkgs.callPackage ./wallpapers.nix {});
 in
 {
+  # System-wide packages available to all users
   environment.systemPackages = with pkgs; [
-    vim
-    wget
-    nitch
-    git
-    lazygit
-    gh
-    kitty
-    unzip
-    neovim
-    zellij
-    tmux
-    picom
-    rofi
-    redis
-    xwallpaper
-    oh-my-posh
-    brightnessctl
-    pamixer
-    udisks2
-    eject
-    direnv
-    libnotify
-    dunst
-    maim
-    slop
-    xbindkeys
-    alsa-utils
-    libinput
-    blueman
-    bluez
-    xclip
-    xcb-util-cursor
-    libreoffice
-    feh
-    wallpapers
+    # Core utilities
+    vim                 # Text editor
+    wget                # File downloader
+    nitch               # System info fetch tool
+    git                 # Version control
+    lazygit             # Terminal UI for git
+    gh                  # GitHub CLI
+    unzip               # Archive extraction
+    
+    # Terminal emulators & multiplexers
+    kitty               # GPU-accelerated terminal
+    zellij              # Modern terminal multiplexer
+    tmux                # Traditional terminal multiplexer
+    
+    # Development tools
+    neovim              # Modern Vim
+    direnv              # Per-directory environment variables
+    redis               # In-memory data store
+    
+    # Window manager & desktop environment
+    picom               # Compositor for X11
+    rofi                # Application launcher
+    xwallpaper          # Wallpaper setter
+    feh                 # Image viewer and wallpaper setter
+    
+    # System utilities
+    brightnessctl       # Screen brightness control
+    pamixer             # PulseAudio mixer
+    udisks2             # Disk management
+    eject               # Eject removable media
+    libnotify           # Desktop notifications library
+    dunst               # Notification daemon
+    alsa-utils          # ALSA sound utilities
+    libinput            # Input device management
+    
+    # Bluetooth management
+    blueman             # Bluetooth manager GUI
+    bluez               # Bluetooth stack
+    
+    # Screenshot tools
+    maim                # Screenshot utility
+    slop                # Screen region selector
+    
+    # X11 utilities
+    xbindkeys           # Key binding utility
+    xclip               # Clipboard utility
+    xcb-util-cursor     # X11 cursor utilities
+    
+    # Productivity
+    libreoffice         # Office suite
+    
+    # Custom packages
+    wallpapers          # Custom wallpaper collection
   ];
 
+  # Font configuration
   fonts.fontDir.enable = true;
-
+  
   fonts.packages = with pkgs; [
+    # Nerd Fonts (fonts with icons for terminal)
     nerd-fonts.jetbrains-mono
-    corefonts
-    vista-fonts
     nerd-fonts.lilex
     nerd-fonts.ubuntu
+    
+    # Microsoft fonts
+    corefonts           # Arial, Times New Roman, etc.
+    vista-fonts         # Calibri, Cambria, etc.
   ];
 }
diff --git a/modules/nixos/services.nix b/modules/nixos/services.nix
index b47cead..80bb922 100644
--- a/modules/nixos/services.nix
+++ b/modules/nixos/services.nix
@@ -1,43 +1,55 @@
 { pkgs, ... }:
 
 {
+  # X11 display server configuration
   services.xserver = {
     enable = true;
+    # Keyboard repeat rate settings (faster repeat for better UX)
     autoRepeatDelay = 200;
     autoRepeatInterval = 35;
+    # Qtile tiling window manager
     windowManager.qtile.enable = true;
+    # Set wallpaper on X11 startup
     displayManager.sessionCommands = ''
       xwallpaper --zoom /home/balraj/nixos-dotfiles/modules/nixos/wallpapers/Pictures/nix.png'';
   };
 
+  # Ly display manager (minimal and aesthetic login screen)
   services.displayManager.ly = {
     enable = true;
     settings = {
-      animation = "matrix";
-      bigclock = true;
+      animation = "matrix";  # Matrix-style animation
+      bigclock = true;       # Show large clock on login
     };
   };
 
+  # CUPS printing system
   services.printing.enable = true;
-
+  # Canon printer drivers
   services.printing.drivers = [ pkgs.cnijfilter2 ];
 
+  # PipeWire audio server (modern replacement for PulseAudio)
   services.pipewire = {
     enable = true;
-    pulse.enable = true;
+    pulse.enable = true;  # PulseAudio compatibility
   };
 
+  # Touchpad/trackpad support for laptops
   services.libinput.enable = true;
 
+  # XDG Desktop Portal (for screen sharing, file pickers, etc.)
   xdg.portal = {
     enable = true;
     config.common.default = [ "*" ];
   };
 
+  # Flatpak support for additional app installation
   services.flatpak.enable = true;
 
+  # Tailscale VPN service
   services.tailscale.enable = true;
 
+  # Bluetooth MPRIS media control proxy
   systemd.user.services.mpris-proxy = {
     description = "Mpris proxy";
     after = [ "network.target" "sound.target" ];
@@ -45,31 +57,36 @@
     serviceConfig.ExecStart = "${pkgs.bluez}/bin/mpris-proxy";
   };
 
+  # Docker container runtime (rootless mode for better security)
   virtualisation.docker.enable = true;
   virtualisation.docker.rootless = {
     enable = true;
-    setSocketVariable = true;
+    setSocketVariable = true;  # Set DOCKER_HOST environment variable
   };
 
+  # Bluetooth hardware support
   hardware.bluetooth.enable = true;
-  hardware.bluetooth.powerOnBoot = true;
-
+  hardware.bluetooth.powerOnBoot = true;  # Turn on Bluetooth on boot
   hardware.bluetooth.settings = {
     General = {
-      Experimental = true;
+      Experimental = true;  # Enable experimental features
     };
   };
 
+  # Blueman GUI manager for Bluetooth
   services.blueman.enable = true;
 
+  # Picom compositor (for transparency, shadows, animations)
   services.picom = {
     enable = true;
-    backend = "glx";
-    vSync = true;
+    backend = "glx";  # OpenGL backend for better performance
+    vSync = true;     # Prevent screen tearing
   };
 
+  # SSH server for remote access
   services.openssh.enable = true;
 
+  # Automatic system updates
   system.autoUpgrade.enable = true;
-  system.autoUpgrade.allowReboot = true;
+  system.autoUpgrade.allowReboot = true;  # Allow automatic reboots after updates
 }