LifeAutomationPortal

LifeAutomationPortal

A Personal Ad Intelligence & Life Automation Portal backend service that monitors AdGuard DNS logs, enriches blocked domains with WHOIS data, and logs incidents to Notion.

🚀 Quick Start

Prerequisites

• Node.js (v16+ recommended)
• Redis server (for deduplication)
• AdGuard Home (with control interface enabled)
• Notion account with API access

Installation

1. Clone the repository:

   git clone https://github.com/Sharv619/LifeAutomationPortal.git
   cd LifeAutomationPortal
   

2. Navigate to the backend and install dependencies:

   cd backend
   npm install
   

3. Configure environment variables:

   cp .env.example .env
   # Edit .env with your actual configuration values
   

4. Build the project:

   npm run build
   

Running the Application

Development mode:

npm run dev

Production mode:

npm start

The server will start on http://localhost:3000 (or the port specified in your .env file).

📋 Environment Configuration

Copy .env.example to .env and configure:

Notion Setup

1. Create a new integration in Notion Developers
2. Get your integration token
3. Create a database with these properties:
   • Name (Title)
   • Category (Select)
   • Blocks Detected (Number)
   • Last Seen (Date)
   • Registrar (Text)
   • Organization (Text)
   • Country (Text)
4. Share the database with your integration
5. Copy the database ID and add it to your .env

🏗️ Architecture

Components

• Fastify Server (src/index.ts) - REST API server with health endpoint
• Domain Poller (src/poller.ts) - Monitors AdGuard query logs for blocked domains
• Deduplication (src/dedup.ts) - Prevents duplicate processing using Redis
• Domain Enrichment (src/enrich.ts) - Enriches domains with WHOIS data
• Notion Integration (src/notion.ts) - Logs incidents to Notion database

Data Flow

1. Polling: Every minute, the system fetches blocked domains from AdGuard
2. Deduplication: Each domain is checked against Redis to avoid duplicates
3. Enrichment: New domains are enriched with WHOIS information
4. Logging: Enriched data is stored in your Notion database
5. Cleanup: Processed domains are remembered for 5 minutes to prevent duplicates

API Endpoints

• GET /health - Health check endpoint

🧪 Testing

Run the test suite:

npm test

Run tests with coverage:

npm test -- --coverage

📊 Monitoring

The application provides structured logging for monitoring:

• Server startup - Logs when the server starts and which port
• Polling activity - Logs when checking for new blocked domains
• Processing - Logs when processing new domains
• Notion logging - Logs when incidents are saved to Notion
• Errors - Comprehensive error logging for troubleshooting

🔧 Troubleshooting

Common Issues

1. Redis Connection Error

   • Ensure Redis server is running: redis-server
   • Check REDIS_URL in your .env file

2. AdGuard Connection Error

   • Verify AdGuard Home control interface is enabled
   • Check ADGUARD_BASE_URL points to the correct AdGuard instance

3. Notion Integration Error

   • Ensure integration token is correct and has database access
   • Verify database ID is correct

4. No Domains Being Processed

   • Check AdGuard is actually blocking domains
   • Verify query log endpoint is accessible

Logs

Check the application logs for detailed error information. In development mode, logs appear in the console.

🚦 Health Checks

Use the health endpoint to monitor service status:

curl http://localhost:3000/health

Expected response:

{
  "status": "ok"
}

📁 Project Structure

backend/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── poller.ts         # AdGuard monitoring logic
│   ├── dedup.ts          # Redis deduplication
│   ├── enrich.ts         # WHOIS enrichment
│   └── notion.ts         # Notion integration
├── package.json
├── tsconfig.json
├── jest.config.js
└── .env.example

🤝 Contributing

1. Follow TypeScript best practices
2. Add tests for new functionality
3. Update documentation as needed
4. Use conventional commit messages

📄 License

This project is part of the Personal Ad Intelligence & Life Automation Portal system.