229 lines
9.1 KiB
Markdown
229 lines
9.1 KiB
Markdown
# ⬡ CloudLense
|
|
|
|
Full-stack website monitoring & performance auditing platform powered by **Google Lighthouse** — with real-time progress tracking, team collaboration, billing, and alerting.
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ CloudLense │
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
|
|
│ │ 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 | HTTP HEAD checks every 5 min, response time + SSL tracking |
|
|
| **Alert Engine** | ✅ Real | Evaluates scans against thresholds, auto-resolves on recovery |
|
|
| **Notifications** | ✅ Real | SMTP email (info@dk0.dev) + webhook delivery with debouncing |
|
|
| **Admin Dashboard** | ✅ Real | System stats, user CRUD, org management, payments, coupons, credits, invoices |
|
|
| **Billing & Usage** | ✅ Real | 4 tiers (free/starter/pro/enterprise), usage bars, limit enforcement, coupon system |
|
|
| **Competitor Analysis** | ✅ Real | Lighthouse comparison + response time benchmarking |
|
|
| **Team/Organization** | ✅ Real | Multi-user orgs with 4-level RBAC |
|
|
| **Authentication** | ✅ Real | Supabase Auth (email, OAuth) |
|
|
| **Scheduled Scans** | ✅ Real | Cron-based Lighthouse scans (6h) + uptime checks (5min) |
|
|
| **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) |
|
|
| Email | SMTP (nodemailer) | Self-hosted |
|
|
| Pre-commit | Husky | 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 cloudlense
|
|
|
|
# Install root dependencies (Husky, concurrently)
|
|
npm install
|
|
|
|
# Setup backend
|
|
cd backend
|
|
cp .env.example .env
|
|
npm install
|
|
npm run build
|
|
cd ..
|
|
|
|
# Setup frontend
|
|
cd 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
|
|
|
|
```
|
|
cloudlense/
|
|
├── backend/ # Express.js API + Lighthouse engine
|
|
│ ├── src/
|
|
│ │ ├── index.ts # Server entry, health check, routing
|
|
│ │ └── routes/
|
|
│ │ └── lighthouse.ts # Lighthouse audit + SSE progress
|
|
│ ├── Dockerfile
|
|
│ └── package.json
|
|
│
|
|
├── 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
|
|
│
|
|
├── 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 (22 total)
|
|
npm test
|
|
|
|
# Backend only (11 tests: health, routes, validation, CORS, 404)
|
|
npm run test:backend
|
|
|
|
# Frontend only (11 tests: tier limits, chart components)
|
|
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 + Frontend health checks |
|
|
| `deploy.yml` | Push to `main` / manual dispatch | Build + push Docker images to GHCR, then deploy on your server via SSH |
|
|
|
|
## 🚢 Production Deployment (Own Server)
|
|
|
|
The repository now includes a full CI/CD path for server deployment:
|
|
|
|
1. `deploy.yml` builds both images (`cloudlense-backend`, `cloudlense-frontend`) and pushes them to GHCR.
|
|
2. The same workflow uploads `devops/docker-compose.prod.yml` + `devops/scripts/deploy-prod.sh` to your server.
|
|
3. It then pulls the new image tag (`github.sha`) and restarts the stack with Docker Compose.
|
|
|
|
Server setup once:
|
|
|
|
```bash
|
|
mkdir -p /opt/cloudlense
|
|
cd /opt/cloudlense
|
|
cp /path/to/repo/devops/.env.production.example .env
|
|
# fill .env with real values
|
|
```
|
|
|
|
Required GitHub repository secrets for deployment:
|
|
|
|
| Secret | Description |
|
|
|--------|-------------|
|
|
| `DEPLOY_HOST` | Server hostname or IP |
|
|
| `DEPLOY_PORT` | SSH port (usually `22`) |
|
|
| `DEPLOY_USER` | SSH user with Docker permissions |
|
|
| `DEPLOY_SSH_KEY` | Private SSH key for `DEPLOY_USER` |
|
|
| `DEPLOY_PATH` | Deployment directory on server (e.g. `/opt/cloudlense`) |
|
|
| `GHCR_USERNAME` | GitHub username for GHCR pull |
|
|
| `GHCR_READ_TOKEN` | GitHub token/PAT with `read:packages` |
|
|
|
|
## 🔑 Key API Routes
|
|
|
|
| Route | Method | Description |
|
|
|-------|--------|-------------|
|
|
| `/api/cron/uptime` | GET | Runs uptime checks on all active websites |
|
|
| `/api/cron/scan` | GET | Triggers Lighthouse scans for due websites |
|
|
| `/api/notifications/process` | POST | Processes pending alerts and sends notifications |
|
|
| `/api/admin/stats` | GET | System-wide stats (admin only) |
|
|
| `/api/admin/users` | GET/PATCH/DELETE | User management (admin only) |
|
|
| `/api/admin/organizations` | GET/PATCH | Organization management (admin only) |
|
|
| `/api/admin/payments` | GET/POST | Payment tracking & recording (admin only) |
|
|
| `/api/admin/coupons` | GET/POST/PATCH/DELETE | Coupon management (admin only) |
|
|
| `/api/admin/credits` | GET/POST | Account credit management (admin only) |
|
|
| `/api/admin/invoices` | GET/POST/PATCH | Invoice creation, sending & management (admin only) |
|
|
| `/api/billing/usage` | GET | Current org usage vs tier limits |
|
|
| `/api/competitor-analysis` | GET/POST | Competitor benchmarking |
|
|
|
|
## 🏗 Tier System
|
|
|
|
| Tier | Websites | Scans/mo | Members | Price |
|
|
|------|----------|----------|---------|-------|
|
|
| Free | 3 | 50 | 2 | $0 |
|
|
| Starter | 10 | 500 | 5 | $9/mo |
|
|
| Professional | 50 | 5,000 | 25 | $29/mo |
|
|
| Enterprise | ∞ | ∞ | ∞ | $99/mo |
|
|
|
|
## 🤝 Contributing
|
|
|
|
See [CONTRIBUTING.md](./CONTRIBUTING.md) for branch strategy, code style, and PR process.
|
|
|
|
## 📄 License
|
|
|
|
ISC
|