Enhance README.md with detailed features, installation instructions, and troubleshooting tips

README.md

@@ -1,15 +1,24 @@
 # SimpleGuardHome
 
-A simple web application for checking and managing domain filtering in AdGuard Home.
+A modern web application for checking and managing domain filtering in AdGuard Home. Built with FastAPI and modern JavaScript.
 
 ## Features
 
-- Check if domains are blocked by your AdGuard Home instance
-- One-click domain unblocking
-- Modern, responsive web interface
-- Secure integration with AdGuard Home API
+- 🔍 Real-time domain filtering status checks
+- 🚫 One-click domain unblocking
+- 💻 Modern, responsive web interface with Tailwind CSS
+- 🔄 Live feedback and error handling
+- 📝 Comprehensive logging
+- 🏥 Health monitoring endpoint
+- ⚙️ Environment-based configuration
 
-## Setup
+## Requirements
+
+- Python 3.9 or higher
+- Running AdGuard Home instance
+- AdGuard Home API credentials (if authentication is enabled)
+
+## Installation
 
 1. Clone this repository:
 ```bash
@@ -17,48 +26,126 @@ git clone https://github.com/yourusername/simpleguardhome.git
 cd simpleguardhome
 ```
 
-2. Create a virtual environment and install dependencies:
+2. Create and activate a virtual environment:
 ```bash
 python -m venv venv
-source venv/bin/activate  # On Windows use: venv\Scripts\activate
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+3. Install dependencies:
+```bash
 pip install -r requirements.txt
 ```
 
-3. Configure your environment:
+## Configuration
+
+1. Copy the example environment file:
 ```bash
 cp .env.example .env
 ```
 
-Edit `.env` with your AdGuard Home instance details:
-```
-ADGUARD_HOST=http://localhost
-ADGUARD_PORT=3000
-ADGUARD_USERNAME=your_username
-ADGUARD_PASSWORD=your_password
+2. Edit `.env` with your AdGuard Home settings:
+```env
+ADGUARD_HOST=http://localhost    # AdGuard Home host URL
+ADGUARD_PORT=3000               # AdGuard Home API port
+ADGUARD_USERNAME=admin          # Optional: AdGuard Home username
+ADGUARD_PASSWORD=password       # Optional: AdGuard Home password
 ```
 
 ## Running the Application
 
 Start the application:
 ```bash
-python -m src.simpleguardhome.main
+python -m uvicorn src.simpleguardhome.main:app --reload
 ```
 
-Visit `http://localhost:8000` in your web browser.
+The application will be available at `http://localhost:8000`
 
-## Usage
+## API Endpoints
 
-1. Enter a domain in the input field
-2. Click "Check Domain" or press Enter
-3. View the domain's blocking status
-4. If blocked, use the "Unblock Domain" button to whitelist it
+### Web Interface
+- `GET /` - Main web interface for domain checking and unblocking
+
+### API Endpoints
+- `POST /check-domain` - Check if a domain is blocked
+  - Parameters: `domain` (form data)
+  - Returns: Blocking status and rule information
+
+- `POST /unblock-domain` - Add a domain to the allowed list
+  - Parameters: `domain` (form data)
+  - Returns: Success/failure status
+
+- `GET /health` - Check application and AdGuard Home connection status
+  - Returns: Health status of the application and AdGuard Home connection
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Connection Failed**
+   - Ensure AdGuard Home is running
+   - Verify the host and port in .env are correct
+   - Check if AdGuard Home's API is accessible
+
+2. **Authentication Failed**
+   - Verify username and password in .env
+   - Ensure AdGuard Home authentication is enabled/disabled as expected
+
+3. **Domain Check Failed**
+   - Check AdGuard Home logs for filtering issues
+   - Verify domain format is correct
+   - Ensure AdGuard Home filtering is enabled
+
+### Checking System Status
+
+1. Use the health check endpoint:
+```bash
+curl http://localhost:8000/health
+```
+
+2. Check application logs:
+- The application uses structured logging
+- Look for ERROR level messages for issues
+- Connection problems are logged with detailed error information
 
 ## Development
 
-The application is built with:
-- FastAPI for the backend
-- Tailwind CSS for styling
-- Modern JavaScript for frontend interactivity
+### Project Structure
+
+```
+simpleguardhome/
+├── src/
+│   └── simpleguardhome/
+│       ├── __init__.py
+│       ├── main.py          # FastAPI application
+│       ├── config.py        # Configuration management
+│       ├── adguard.py       # AdGuard Home API client
+│       └── templates/
+│           └── index.html   # Web interface
+├── requirements.txt
+├── setup.py
+├── .env.example
+└── README.md
+```
+
+### Adding New Features
+
+1. Backend Changes:
+   - Add routes in `main.py`
+   - Extend AdGuard client in `adguard.py`
+   - Update configuration in `config.py`
+
+2. Frontend Changes:
+   - Modify `templates/index.html`
+   - Use Tailwind CSS for styling
+   - Follow existing error handling patterns
+
+## Security Notes
+
+- API credentials are handled via environment variables
+- Connections use proper error handling and timeouts
+- Input validation is performed on all endpoints
+- Sensitive information is not exposed in responses
 
 ## License