diff --git a/README.md b/README.md
index 9eccf15..ac79ec8 100644
--- a/README.md
+++ b/README.md
@@ -24,115 +24,171 @@ Agora is a library of voting algorithms like `Moore's`, `Oklahoma` , `Borda` , `
   - [TailwindCSS](https://tailwindcss.com/): A utility-first CSS framework for efficient styling.
   - [zustand](https://zustand.docs.pmnd.rs/getting-started/introduction): A state management library for React, used for managing global state in the Next.js application.
 
-Here's a refined version of the development guide:
-
 ## Development Guide
 
 ### Running Locally
 
-**Clone the Repository**:
+**Clone the Repository:**
 
 ```bash
 git clone https://github.com/AOSSIE-Org/Agora-Blockchain
+cd Agora-Blockchain
 ```
-### Option 1: Docker Setup 
 
-1. **Clone the Repository**:
-   ```bash
-   git clone https://github.com/AOSSIE-Org/Agora-Blockchain
-   cd Agora-Blockchain
-   ```
+## 🔐 Environment Files — Important Notice
 
-2. **Set up Environment Variables**:
+This project uses two types of environment files:
 
-   Create `.env.local` in the `blockchain` directory:
-   ```
-   PRIVATE_KEY=<your_private_key>
-   RPC_URL_SEPOLIA=<your_sepolia_rpc_url>
-   RPC_URL_FUJI=<your_fuji_rpc_url>
-   ETHERSCAN_KEY=<your_etherscan_api_key>
-   ```
+### ✔ .env.example (for local testing only)
 
-   Create `.env.local` in the `client` directory:
-   ```
-   NEXT_PUBLIC_PINATA_JWT=<your_pinata_jwt>
-   ```
+Contains dummy values used for:
+- Running Hardhat tests
+- Local blockchain
+- Local frontend development
 
-3. **Run with Docker Compose**:
-   ```bash
-   docker-compose up --build
-   ```
+Copy these before running:
 
-4. **Access the Application**:
-   - Frontend: http://localhost:3000
-   - Blockchain Node: http://localhost:8545
+**Backend:**
+```bash
+cp blockchain/.env.example blockchain/.env
+```
 
-The application will automatically reload when you make changes to the source code.
+**Frontend:**
+```bash
+cp client/.env.example client/.env.local
+```
 
-### Option 2: Manual Setup
-## Backend
-1. **Navigate to the Blockchain Directory**:
+These dummy values are **ONLY for local development**.
 
-   ```bash
-   cd blockchain
-   ```
+### ✔ .env / .env.local (for real testnet/mainnet deployments)
 
-2. **Install Dependencies**:
+When deploying to actual networks, replace the dummy values with real keys.
 
-   ```bash
-   npm install
-   ```
+**Backend .env format for real deployment:**
+```
+PRIVATE_KEY=<your_real_private_key>
+RPC_URL_AMOY=<your_amoy_rpc>
+RPC_URL_SEPOLIA=<your_sepolia_rpc>
+RPC_URL_FUJI=<your_fuji_rpc>
+RPC_URL_BSC=<your_bsc_rpc>
+ETHERSCAN_KEY=<your_real_etherscan_key>
+```
 
-3. **Test the Contracts**:
+**Frontend .env.local format for real deployment:**
+```
+NEXT_PUBLIC_PINATA_JWT=<your_real_pinata_jwt>
+```
 
-   ```bash
-   npx hardhat test
-   ```
+### ⚠️ Never commit .env or .env.local to GitHub.
 
-4. **Create an `.env.local` file** with the following environment variables:
+---
 
-   ```bash
-   PRIVATE_KEY=<your_private_key>
-   RPC_URL_SEPOLIA=<your_sepolia_rpc_url>
-   RPC_URL_FUJI=<your_fuji_rpc_url>
-   ETHERSCAN_KEY=<your_etherscan_api_key>
-   ```
+## Option 1: Docker Setup
 
-5. **Compile & Deploy Contracts**:
-   ```bash
-   npx hardhat ignition deploy ./ignition/modules/<ContractModule> --network <Network> --verify
-   ```
+**Clone the Repository:**
+```bash
+git clone https://github.com/AOSSIE-Org/Agora-Blockchain
+cd Agora-Blockchain
+```
 
-## Frontend
+**Set up Environment Variables for Local Testing:**
 
-1. **Navigate to the Client Directory**:
+Backend:
+```bash
+cp blockchain/.env.example blockchain/.env
+```
 
-   ```bash
-   cd client
-   ```
+Frontend:
+```bash
+cp client/.env.example client/.env.local
+```
 
-2. **Install Dependencies**:
+**Run with Docker Compose:**
+```bash
+docker-compose up --build
+```
 
-   ```bash
-   npm install
-   ```
+**Access the Application:**
+- Frontend: http://localhost:3000
+- Blockchain Node: http://localhost:8545
 
-3. **Run the Application**:
+The application will automatically reload when you make changes.
 
-   ```bash
-   npm run dev
-   ```
+---
 
-4. **Create an `.env.local` file** with the following environment variables:
+## Option 2: Manual Setup
 
-   ```bash
-   NEXT_PUBLIC_PINATA_JWT=<your_pinata_jwt>
-   ```
+### Backend
+
+**Navigate to the Blockchain Directory:**
+```bash
+cd blockchain
+```
+
+**Install Dependencies:**
+```bash
+npm install
+```
+
+**Local Testing Environment Setup:**
+```bash
+cp .env.example .env
+```
+
+This includes dummy:
+- `PRIVATE_KEY`
+- `RPC URLs`
+- `ETHERSCAN_KEY`
+
+**Run Tests:**
+```bash
+npx hardhat test
+```
+
+**Real Deployment Environment (replace with real values):**
+```
+PRIVATE_KEY=<your_real_private_key>
+RPC_URL_SEPOLIA=<your_real_rpc>
+RPC_URL_FUJI=<your_real_rpc>
+ETHERSCAN_KEY=<your_real_etherscan_key>
+```
+
+**Compile & Deploy Contracts:**
+```bash
+npx hardhat ignition deploy ./ignition/modules/<ContractModule> --network <Network> --verify
+```
+
+### Frontend
+
+**Navigate to the Client Directory:**
+```bash
+cd client
+```
+
+**Install Dependencies:**
+```bash
+npm install
+```
+
+**Local Development Environment:**
+```bash
+cp .env.example .env.local
+```
+
+**Real Deployment Environment:**
+```
+NEXT_PUBLIC_PINATA_JWT=<your_real_pinata_jwt>
+```
+
+**Run the Application:**
+```bash
+npm run dev
+```
 
-5. **Visit the Live App at**:
-   **[localhost](http://localhost:3000/)**
+**Visit the Live App:**
+👉 **[http://localhost:3000/](http://localhost:3000/)**
 
-## About smart contracts
+## About Smart Contracts
 
 The architecture of your Election Factory contract is designed to facilitate the creation and management of elections on the blockchain, incorporating cross-chain voting capabilities through Chainlink's Cross-Chain Interoperability Protocol (CCIP). Below is a detailed explanation:
 
@@ -140,17 +196,17 @@ The architecture of your Election Factory contract is designed to facilitate the
 
 The `ElectionFactory` contract serves as the core component of the election creation and management system. It is responsible for generating new election instances, handling cross-chain voting, and maintaining a record of active elections. The contract leverages several other contracts and libraries to achieve its functionality, including the `Election`, `BallotGenerator`, and `ResultCalculator` contracts, as well as Chainlink's CCIP components.
 
-- ### Key Features:
+### Key Features
 
-  - Election Creation: Utilizes a clonable election template (electionGenerator) to efficiently create new election contracts.
-  - Ballot and Result Handling: Generates ballots using the BallotGenerator contract and calculates election results with a dedicated ResultCalculator contract.
-  - Cross-Chain Voting: Implements Chainlink's Cross-Chain Interoperability Protocol (CCIP) to allow voting from multiple blockchain networks.
+- **Election Creation**: Utilizes a clonable election template (electionGenerator) to efficiently create new election contracts.
+- **Ballot and Result Handling**: Generates ballots using the BallotGenerator contract and calculates election results with a dedicated ResultCalculator contract.
+- **Cross-Chain Voting**: Implements Chainlink's Cross-Chain Interoperability Protocol (CCIP) to allow voting from multiple blockchain networks.
 
-- ### Efficiency and Security:
+### Efficiency and Security
 
-  - Clonable Contracts: Reduces deployment costs and resource usage by cloning a pre-deployed election template.
-  - Owner Management: Ensures only the election creator can delete or modify their election, providing security and control.
-  - Whitelisted Cross-Chain Communication: Only allows approved contracts to send votes across chains, preventing unauthorized access.
+- **Clonable Contracts**: Reduces deployment costs and resource usage by cloning a pre-deployed election template.
+- **Owner Management**: Ensures only the election creator can delete or modify their election, providing security and control.
+- **Whitelisted Cross-Chain Communication**: Only allows approved contracts to send votes across chains, preventing unauthorized access.
 
 ## Deployed Instances
 
diff --git a/blockchain/.env.example b/blockchain/.env.example
index d26c2bc..74d0ade 100644
--- a/blockchain/.env.example
+++ b/blockchain/.env.example
@@ -1,6 +1,17 @@
-PRIVATE_KEY = ENTER_YOUR_KEY_VALUE
-RPC_URL_SEPOLIA = ENTER_YOUR_KEY_VALUE
-RPC_URL_FUJI = ENTER_YOUR_KEY_VALUE
-RPC_URL_AMOY = ENTER_YOUR_KEY_VALUE
-RPC_URL_BSC = ENTER_YOUR_KEY_VALUE
-ETHERSCAN_KEY = ENTER_YOUR_KEY_VALUE
+# ----------------------------------------------------------
+# Example environment file for local development and testing
+# ----------------------------------------------------------
+
+# Dummy private key for Hardhat local network.
+# DO NOT use your real private key here.
+PRIVATE_KEY=0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+
+# For running tests locally, we use Hardhat's built-in RPC.
+# These RPC URLs do NOT require real networks.
+RPC_URL_AMOY=http://127.0.0.1:8545
+RPC_URL_SEPOLIA=http://127.0.0.1:8545
+RPC_URL_FUJI=http://127.0.0.1:8545
+RPC_URL_BSC=http://127.0.0.1:8545
+
+# Dummy API key
+ETHERSCAN_KEY=dummy
diff --git a/client/.env.example b/client/.env.example
index 16d4900..fb67276 100644
--- a/client/.env.example
+++ b/client/.env.example
@@ -1,4 +1,6 @@
-NEXT_PUBLIC_SEPOLIA_RPC_URL = ENTER_RPC_URL
-NEXT_PUBLIC_AMOY_RPC_URL = ENTER_RPC_URL
-NEXT_PUBLIC_FUJI_RPC_URL = ENTER_RPC_URL
-NEXT_PUBLIC_PINATA_JWT = ENTER_PINATA_API_KEY
\ No newline at end of file
+# ----------------------------------------------------------
+# Example environment file for Next.js frontend
+# ----------------------------------------------------------
+
+# Replace with your real Pinata JWT token when using IPFS
+NEXT_PUBLIC_PINATA_JWT=your_pinata_jwt_here
diff --git a/client/package-lock.json b/client/package-lock.json
index 6143ee6..a3baa66 100644
--- a/client/package-lock.json
+++ b/client/package-lock.json
@@ -16583,6 +16583,126 @@
           "optional": true
         }
       }
+    },
+    "node_modules/@next/swc-darwin-x64": {
+      "version": "14.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-darwin-x64/-/swc-darwin-x64-14.2.4.tgz",
+      "integrity": "sha512-QVadW73sWIO6E2VroyUjuAxhWLZWEpiFqHdZdoQ/AMpN9YWGuHV8t2rChr0ahy+irKX5mlDU7OY68k3n4tAZTg==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-linux-arm64-gnu": {
+      "version": "14.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-gnu/-/swc-linux-arm64-gnu-14.2.4.tgz",
+      "integrity": "sha512-KT6GUrb3oyCfcfJ+WliXuJnD6pCpZiosx2X3k66HLR+DMoilRb76LpWPGb4tZprawTtcnyrv75ElD6VncVamUQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-linux-arm64-musl": {
+      "version": "14.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-arm64-musl/-/swc-linux-arm64-musl-14.2.4.tgz",
+      "integrity": "sha512-Alv8/XGSs/ytwQcbCHwze1HmiIkIVhDHYLjczSVrf0Wi2MvKn/blt7+S6FJitj3yTlMwMxII1gIJ9WepI4aZ/A==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-linux-x64-gnu": {
+      "version": "14.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-gnu/-/swc-linux-x64-gnu-14.2.4.tgz",
+      "integrity": "sha512-ze0ShQDBPCqxLImzw4sCdfnB3lRmN3qGMB2GWDRlq5Wqy4G36pxtNOo2usu/Nm9+V2Rh/QQnrRc2l94kYFXO6Q==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-linux-x64-musl": {
+      "version": "14.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-linux-x64-musl/-/swc-linux-x64-musl-14.2.4.tgz",
+      "integrity": "sha512-8dwC0UJoc6fC7PX70csdaznVMNr16hQrTDAMPvLPloazlcaWfdPogq+UpZX6Drqb1OBlwowz8iG7WR0Tzk/diQ==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-win32-arm64-msvc": {
+      "version": "14.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-arm64-msvc/-/swc-win32-arm64-msvc-14.2.4.tgz",
+      "integrity": "sha512-jxyg67NbEWkDyvM+O8UDbPAyYRZqGLQDTPwvrBBeOSyVWW/jFQkQKQ70JDqDSYg1ZDdl+E3nkbFbq8xM8E9x8A==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-win32-ia32-msvc": {
+      "version": "14.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-ia32-msvc/-/swc-win32-ia32-msvc-14.2.4.tgz",
+      "integrity": "sha512-twrmN753hjXRdcrZmZttb/m5xaCBFa48Dt3FbeEItpJArxriYDunWxJn+QFXdJ3hPkm4u7CKxncVvnmgQMY1ag==",
+      "cpu": [
+        "ia32"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
+    },
+    "node_modules/@next/swc-win32-x64-msvc": {
+      "version": "14.2.4",
+      "resolved": "https://registry.npmjs.org/@next/swc-win32-x64-msvc/-/swc-win32-x64-msvc-14.2.4.tgz",
+      "integrity": "sha512-tkLrjBzqFTP8DVrAAQmZelEahfR9OxWpFR++vAI9FBhCiIxtwHwBHC23SBHCTURBtwB4kc/x44imVOnkKGNVGg==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">= 10"
+      }
     }
   }
 }