PulseGuard 🛡️ — AI-Powered API Monitoring & Incident Analysis Platform

PulseGuard is an API monitoring platform that continuously checks the health of target APIs, triggers alerts when they go offline, and uses AI to diagnose why they failed.

It features a real-time Next.js dashboard that receives instant status updates via WebSockets when API health changes.

---

🏗️ How it Works

1. Next.js Frontend: Displays live API status, latency charts, and AI incident logs.
2. FastAPI Backend: Handles user authentication, configuration, background API monitoring, and WebSocket streams.
3. Asyncio Scheduler & Redis: Runs non-blocking API health checks in the background using native Python asyncio tasks.
4. AI Diagnostics: Queries LLMs to analyze logs and suggest troubleshooting steps.

---

⚡ Key Features

• Background Checks: Offloads API checks to native asyncio background tasks so the web server stays fast.
• Smart Alerts: Sends emails and webhooks only when an API's status changes (e.g., goes offline or recovers) to avoid alert spam.
• AI Diagnostics: Automatically generates root-cause analyses and suggestions using AI when an API fails.
• Fast Caching: Caches the latest API check results in Redis for instant dashboard loads.
• API Protection: Protects sign-up, login, and check routes with a custom Redis rate limiter.
• Real-time Streaming: Streams live API updates directly to the browser client via WebSockets.

---

🛠️ Tech Stack

• Backend: Python, FastAPI, Asyncio, SQLAlchemy ORM, PostgreSQL, Redis, HTTPX, Groq SDK
• Frontend: Next.js (App Router), React, Tailwind CSS, WebSockets
• DevOps: Docker, Docker Compose
• Testing: Pytest

---

🚀 How to Run

Option A: With Docker (Recommended)

1. Clone the repository and run:

   docker compose up --build

   (Note: On Linux, if you get a permission denied error, run with sudo docker compose up --build or add your user to the docker group).
2. Access the services:
   • Frontend UI: http://localhost:3000
   • Backend API Docs: http://localhost:8000/docs

---

Option B: Local Setup (Without Docker)

1. Backend Setup

1. Prepare PostgreSQL: Make sure your local PostgreSQL database server is running and create a database named pulseguard.
2. Setup environment & seed data:

   cd server
   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   cp .env.example .env       # Copy and configure environment variables
   python seed.py             # Seed initial users and monitoring endpoints

3. Start the API Server:

   uvicorn app.main:app --reload --port 8000

   (Note: Endpoint health checks are automatically scheduled and executed in the background by native asyncio tasks on FastAPI startup. You only need to run this single uvicorn server command.)

2. Frontend Setup

cd client
npm install
cp .env.local.example .env.local  # Copy frontend environment variables
npm run dev

Open http://localhost:3000 in your browser.

---

🧪 Running Tests

To run backend automated tests:

cd server
pytest