aitest-reasonml-mon-fbk/ARCHITECTURE.md

Project Architecture

Overview

Website Monitor is a full-stack web application built with OCaml and ReasonML, designed for monitoring website availability and sending alerts on status deviations.

Technology Stack

Core Technologies

• Language: OCaml 5.0+ with ReasonML syntax support
• Web Framework: Dream - Fast, type-safe web framework for OCaml
• Frontend: server-reason-react - Server-side React with ReasonML
• Database: PostgreSQL 16 with Caqti (OCaml database driver)
• Async: Lwt (Lightweight Threads) - Cooperative threading library
• Containerization: Docker & Docker Compose

Key Libraries

• dream - Web server and routing
• server-reason-react - Server-side React rendering
• caqti / caqti-dream - Database connection pooling and queries
• lwt / lwt_ppx - Async programming
• yojson - JSON parsing and generation
• cohttp-lwt-unix - HTTP client for website checks
• ocaml-ssl - SSL/TLS support
• ptime - Time handling

Architecture

Layered Architecture

┌─────────────────────────────────────────────────────────┐
│                    Presentation Layer                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Admin UI   │  │  REST API    │  │  Health API  │ │
│  │ (React + SS) │  │  (JSON/HTTP) │  │   (JSON)     │ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                     Business Logic                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐ │
│  │   Monitor    │  │    Alert     │  │   Scheduler  │ │
│  │   (Checks)   │  │ (Email/Web)  │  │  (Background)│ │
│  └──────────────┘  └──────────────┘  └──────────────┘ │
└─────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────┐
│                    Data Access Layer                     │
│  ┌──────────────┐  ┌──────────────┐                     │
│  │  Database    │  │  Connection  │                     │
│  │  (Caqti)     │  │    Pool      │                     │
│  └──────────────┘  └──────────────┘                     │
└─────────────────────────────────────────────────────────┘
                            ↓
                    ┌──────────────┐
                    │  PostgreSQL   │
                    └──────────────┘

Core Components

1. Application Entry Point (bin/main.ml)

• Initializes Dream web server
• Configures middleware (CORS, logging)
• Defines route handlers
• Starts background scheduler
• Listens on port 8080

2. Database Layer (lib/database.ml)

Models:

• Website - Monitored websites configuration
• Alert - Alert configurations per website
• CheckHistory - Historical check results

Features:

• Connection pooling (5 connections)
• Type-safe queries using Caqti
• Automatic schema initialization
• Cascade deletion for data integrity

3. Monitoring Logic (lib/monitor.ml)

Functions:

• check_website - Performs HTTP check with timeout
• check_and_store_website - Check and persist result
• check_all_active_websites - Batch check all active sites
• get_website_status - Current status with history

Features:

• Configurable timeouts
• Response time measurement
• Error handling and logging
• Automatic alert triggering

4. Alert System (lib/alert.ml)

Alert Types:

• Email (SMTP)
• Webhook (HTTP POST)

Features:

• Template-based email messages
• Configurable webhook payloads
• Test alert functionality
• Alert history tracking

5. REST API (lib/api.ml)

Endpoints:

• GET /api/websites - List all websites
• POST /api/websites - Create website
• GET /api/websites/:id - Get website details
• PUT /api/websites/:id - Update website
• DELETE /api/websites/:id - Delete website
• POST /api/websites/:id/check - Trigger immediate check
• GET /api/websites/:id/history - Get check history
• GET /api/websites/:id/status - Get current status
• GET /api/alerts - List all alerts
• POST /api/alerts - Create alert
• GET /api/alerts/:id - Get alert details
• PUT /api/alerts/:id - Update alert
• DELETE /api/alerts/:id - Delete alert
• GET /api/stats/summary - Get statistics

Features:

• JSON request/response
• Proper HTTP status codes
• Error handling with messages
• Input validation

6. Admin UI (lib/ui.ml)

Pages:

• Dashboard - Overview with stats and status cards
• Websites - Manage monitored websites
• Alerts - Configure alerts
• Settings - Application configuration

Features:

• Server-side React rendering
• Tailwind CSS for styling
• Auto-refresh (60 seconds)
• Responsive design
• Interactive buttons (delete, test, etc.)

7. Scheduler (lib/scheduler.ml)

Functions:

• start - Start background monitoring
• stop - Stop monitoring
• status - Get scheduler status
• scheduler_loop - Main monitoring loop

Features:

• Runs every minute
• Checks due websites
• Cleans old history (30 days)
• Graceful shutdown support

Database Schema

Websites Table

CREATE TABLE websites (
  id BIGSERIAL PRIMARY KEY,
  name TEXT NOT NULL,
  url TEXT NOT NULL UNIQUE,
  expected_status INTEGER NOT NULL DEFAULT 200,
  timeout INTEGER NOT NULL DEFAULT 30,
  check_interval INTEGER NOT NULL DEFAULT 300,
  active BOOLEAN NOT NULL DEFAULT true,
  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
  last_checked TIMESTAMP WITH TIME ZONE,
  last_status INTEGER
);

Alerts Table

CREATE TABLE alerts (
  id BIGSERIAL PRIMARY KEY,
  website_id BIGINT NOT NULL REFERENCES websites(id) ON DELETE CASCADE,
  alert_type TEXT NOT NULL,
  config JSONB NOT NULL,
  enabled BOOLEAN NOT NULL DEFAULT true,
  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
  UNIQUE(website_id, alert_type)
);

Check Histories Table

CREATE TABLE check_histories (
  id BIGSERIAL PRIMARY KEY,
  website_id BIGINT NOT NULL REFERENCES websites(id) ON DELETE CASCADE,
  status_code INTEGER NOT NULL,
  response_time REAL NOT NULL,
  error_message TEXT,
  checked_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW()
);

Docker Architecture

Multi-Stage Build

1. Base Stage: Install system dependencies
2. Build Stage: Compile OCaml code with CPU constraint
3. Runtime Stage: Minimal Debian with only runtime dependencies

CPU Constraints

ENV OPAMJOBS=1  # Single job for compilation

cpus: '1.0'     # Limit to 1 CPU core
cpuset: '0'     # Pin to first CPU

Services

1. PostgreSQL: Database storage
2. Redis: Cache and queues (optional enhancement)
3. App: Main application

Security Considerations

Implemented

• SQL injection prevention (parameterized queries)
• Environment-based configuration
• Secrets not in code
• Database user with limited privileges
• Health check endpoint

Recommendations for Production

1. Add API authentication (JWT, API keys)
2. Use HTTPS (reverse proxy)
3. Input validation and sanitization
4. Rate limiting on API endpoints
5. Audit logging
6. Regular security updates

Performance Optimizations

Database

• Connection pooling (5 connections)
• Indexed columns (id, website_id)
• Efficient queries with LIMIT
• Regular cleanup of old history

Application

• Async operations (Lwt)
• Background scheduler for checks
• Minimal dependencies
• Single-threaded OCaml runtime

Monitoring

• Configurable check intervals
• Timeout limits (default: 30s)
• Efficient status tracking
• Health checks

Scalability Considerations

Current Design

• Single instance deployment
• Centralized database
• Connection pooling
• Efficient queries

Scaling Options

1. Vertical: More CPU cores, RAM
2. Horizontal: Multiple app instances with load balancer
3. Database: Read replicas, connection pooling optimization
4. Monitoring: Queue-based system for large scale

Future Enhancements

Planned Features

• SMS alerts (Twilio)
• Slack integration
• Performance metrics (response time graphs)
• Multi-user support with authentication
• Custom check scripts (JS, Python)
• Export reports (CSV, PDF)
• Mobile app
• Public status pages

Technical Improvements

• GraphQL API
• WebSocket for real-time updates
• Caching layer (Redis)
• Rate limiting
• API versioning
• OAuth2/OIDC authentication
• Monitoring dashboard (Prometheus, Grafana)

Development Workflow

Local Development

make build      # Build with dune
make test       # Run tests
make run        # Run locally
make repl       # OCaml REPL

Docker Development

docker-compose -f docker/docker-compose.dev.yml up -d
make docker-logs

Testing

make test       # Run all tests

Monitoring and Observability

Application Metrics

• Website status (healthy/unhealthy)
• Check response times
• Alert trigger count
• Database query performance

Logging

• Application logs (JSON format)
• Database query logs
• HTTP request/response logs
• Error logs with stack traces

Health Checks

• HTTP: GET /health
• Database: Connection check
• Scheduler: Running status

Error Handling

Strategy

• Graceful degradation
• Retry logic for transient failures
• Detailed error messages
• Comprehensive logging

Error Types

• Network errors (connection timeout)
• Database errors (connection lost)
• Configuration errors (invalid settings)
• Application errors (bugs)

Deployment Considerations

Production Checklist

• Strong secret key
• SMTP credentials configured
• HTTPS enabled
• Database backups scheduled
• Resource limits configured
• Monitoring/alerts set up
• SSL certificates valid
• Firewall rules configured

Backup Strategy

1. Database: pg_dump daily
2. Configuration: Version control
3. Application: Docker image versions

---

This architecture provides a solid foundation for a scalable, maintainable website monitoring application.