cloudlense/README.md

# 🔍 Website Monitoring Platform

Full-stack website monitoring platform that uses **Google Lighthouse** to audit performance, SEO, accessibility, and best practices — with real-time progress tracking, team collaboration, and alerting.

```
┌─────────────────────────────────────────────────────────┐
│                    Website Monitoring                     │
│                                                          │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────┐   │
│  │ Frontend  │───▶│ Backend  │───▶│  PostgreSQL (DB)  │   │
│  │ Next.js   │    │ Express  │    │  via Supabase     │   │
│  │ Port 3000 │◀───│ Port 5000│    └──────────────────┘   │
│  └──────────┘    └──────────┘                            │
│       │               │                                  │
│       │               ▼                                  │
│       │          ┌──────────┐                            │
│       │          │Lighthouse│                            │
│       └─── SSE ──│ + Chrome │                            │
│       (progress) │ Headless │                            │
│                  └──────────┘                            │
└─────────────────────────────────────────────────────────┘
```

## ✨ Features

| Feature | Status | Description |
|---------|--------|-------------|
| **Lighthouse Audits** | ✅ Real | Performance, SEO, accessibility, best practices scores |
| **Real-time Progress** | ✅ Real | Server-Sent Events stream during scans |
| **Dashboard** | ✅ Real | Overview with charts, metrics, and website list |
| **Performance Monitoring** | ✅ Real | Track scores over time with Recharts |
| **SEO Analysis** | ✅ Real | SEO score tracking and recommendations |
| **Uptime Monitoring** | ✅ Real | Periodic uptime checks with alerting |
| **Team/Organization** | ✅ Real | Multi-user orgs with role-based access |
| **Alerts** | ✅ Real | Configurable alerts for downtime, performance, SSL |
| **Competitor Analysis** | ✅ Real | Compare your site metrics against competitors |
| **Authentication** | ✅ Real | Supabase Auth (email, OAuth) |
| **Scheduled Scans** | ✅ Real | Cron-based automated Lighthouse scans every 6 hours |
| **Website Crawler** | ✅ Real | Crawl and discover pages on your websites |

## 🛠 Tech Stack

| Layer | Technology | Cost |
|-------|-----------|------|
| Frontend | Next.js 15, React 19, TypeScript, Tailwind CSS 4, Shadcn/UI | Free |
| Backend | Express.js, TypeScript, Node.js 18+ | Free |
| Database | PostgreSQL via Supabase | Free tier |
| Auth | Supabase Auth | Free tier |
| Auditing | Google Lighthouse + Headless Chrome | Free (OSS) |
| Charts | Recharts + Chart.js | Free (OSS) |
| CI/CD | GitHub Actions | Free (public repos) |
| Containers | Docker + Docker Compose | Free |
| Linting | ESLint + Prettier | Free (OSS) |
| Testing | Jest + Supertest + Testing Library | Free (OSS) |
| Pre-commit | Husky + lint-staged | Free (OSS) |

## 🚀 Quick Start

### Prerequisites
- Node.js 18+
- npm
- Docker & Docker Compose (for full stack)
- Supabase account (free tier)

### Option 1: Local Development

```bash
# Clone the repo
git clone <repo-url>
cd website-monitoring

# Install root dependencies (Husky, concurrently)
npm install

# Setup backend
cd website-monitoring-backend
cp .env.example .env
npm install
npm run build
cd ..

# Setup frontend
cd website-monitoring-frontend
cp .env.example .env    # Fill in your Supabase keys
npm install
cd ..

# Run everything
npm run dev
```

### Option 2: Docker Compose

```bash
# Copy and fill in environment variables
cp .env.example .env

# Start all services
npm run docker:up

# Access at http://localhost:3000
```

## 📁 Project Structure

```
website-monitoring/
├── website-monitoring-backend/    # Express.js API + Lighthouse engine
│   ├── src/
│   │   ├── index.ts              # Server entry, health check, routing
│   │   └── routes/
│   │       └── lighthouse.ts     # Lighthouse audit + SSE progress
│   ├── Dockerfile
│   └── package.json
│
├── website-monitoring-frontend/   # Next.js 15 dashboard
│   ├── src/
│   │   ├── app/                  # Pages & API routes (20+ endpoints)
│   │   ├── components/           # React components (dashboard, UI, auth)
│   │   ├── services/             # Business logic (scanning, monitoring)
│   │   └── types/                # TypeScript type definitions
│   ├── Dockerfile
│   └── package.json
│
├── website-monitoring-devops/     # Infrastructure
│   ├── docker-compose.yml        # Full stack orchestration
│   └── .devcontainer/            # VS Code Dev Container config
│
├── .github/
│   ├── workflows/
│   │   ├── backend.yml           # Backend CI: lint, test, build
│   │   ├── frontend.yml          # Frontend CI: lint, test, build
│   │   └── docker.yml            # Docker Compose integration test
│   └── pull_request_template.md
│
├── CONTRIBUTING.md               # Branch strategy, code review, guidelines
├── .env.example                  # Unified environment template
└── package.json                  # Root scripts (dev, build, test, lint)
```

## 🧪 Testing

```bash
# Run all tests
npm test

# Backend only (3 tests: health, API info, validation)
npm run test:backend

# Frontend only (component tests)
npm run test:frontend
```

## 📊 CI/CD Pipelines

| Workflow | Trigger | What it does |
|----------|---------|-------------|
| `backend.yml` | Push/PR to backend | Lint → Test → Build (Node 18 & 20) |
| `frontend.yml` | Push/PR to frontend | Lint → Test → Build (Node 18 & 20) |
| `docker.yml` | Push/PR to main | Docker Compose build → Backend health check |

## 🤝 Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for branch strategy, code style, and PR process.

## 📄 License

ISC