Cloudlog

Cloudlog is a self‑hosted PHP web application that serves as an amateur radio logbook. It exposes a browser‑based UI for recording QSOs (contacts) and provides a set of REST endpoints that allow programmatic access to the data. The core idea is simple: persist QSO records in a relational database and render them via MVC‑style PHP templates. From a developer’s point of view, the application is a lightweight stack that can be dropped into an existing LAMP/LEMP environment or containerized for experimentation.

Technical Stack & Architecture

• Language & Framework: Pure PHP 7.4/8.2 with a custom MVC layer; no heavy frameworks such as Laravel or Symfony are used, which keeps the codebase small and easy to audit. Routing is handled by a front‑controller that dispatches requests based on the $_GET['route'] parameter.
• Database: MySQL 5.7+ (or MariaDB). The schema is defined in database.sql and includes tables for users, contacts, callsigns, and auxiliary data (e.g., bands, modes). All queries are parameterized to mitigate SQL injection risks.
• Web Server: Apache is the primary target, with an .htaccess file that rewrites URLs to the front controller. The README notes that Nginx should work with minor adjustments, indicating a fairly generic Apache configuration.
• Testing: End‑to‑end Cypress tests are maintained in a tests/ folder. The CI pipeline runs these tests on every push to the dev branch, ensuring that UI changes do not break existing workflows.

Core Capabilities & APIs

• QSO CRUD: Create, read, update, and delete contacts via web forms or the REST API. The API returns JSON responses with HTTP status codes, making it straightforward to integrate with external scripts (e.g., APRS clients).
• Import/Export: Supports DXCC, Logbook of The World (LoTW), and QRZ.com file formats. Importers are written in PHP and can be extended to support new formats.
• Reporting: Generates statistics on contacts per band, mode, and day. These reports are rendered as HTML tables but can be consumed programmatically by polling the /api/report endpoint.
• User Management: Role‑based access control (admin, operator) is implemented via PHP sessions and a simple users table. Passwords are hashed with bcrypt.

Deployment & Infrastructure

• Self‑Hosting Requirements: Linux OS, Apache/Nginx, PHP 7.4+ (8.2 compatible), MySQL/MariaDB. The README explicitly states that Docker is not officially supported, but a community‑maintained docker-compose.yml exists for local development. For production, the application can be deployed on a VPS or cloud instance with minimal overhead.
• Scalability: Cloudlog is stateless aside from the database connection, so horizontal scaling can be achieved by adding more web servers behind a load balancer and sharing the same MySQL instance. Caching is minimal, but PHP’s opcode cache (OPcache) can be enabled for performance gains.
• Containerization: While not officially supported, developers can containerize the stack using a custom Dockerfile that installs PHP, Apache, and MySQL. The provided docker-compose.yml demonstrates a dev environment but can be adapted for CI/CD pipelines.

Integration & Extensibility

• Plugin System: The codebase exposes a lightweight hook mechanism (hooks.php) that allows third‑party modules to register callbacks on events such as qso_created or user_login. This enables developers to add features like automated LoTW uploads without modifying core files.
• Webhooks: Outgoing webhooks can be configured in the admin panel to notify external services when a QSO is logged. The payloads are JSON and can be authenticated via HMAC signatures.
• API Documentation: Although the README lacks a dedicated Swagger spec, the REST endpoints are self‑documenting via inline comments and can be reverse engineered from the api/ folder. Community members often share Postman collections on GitHub.
• Customization: The front‑end uses Blade‑style templates (templates/) and a CSS framework (likely Bootstrap). Developers can override templates by placing files in a custom/ directory, allowing UI tweaks without touching core code.

Developer Experience

• Configuration: A single .env file holds database credentials and optional settings. The install wizard populates the config.php file during setup, making the initial bootstrap painless.
• Documentation Quality: The README covers installation, CI, and testing but lacks deep architectural diagrams. However, the inline comments in PHP files are generally helpful, and the community wiki provides additional guidance.
• Community Support: Issues are triaged on GitHub, and the dev branch is the active development line. The presence of Cypress tests indicates a mature testing culture, which reassures contributors that changes are safe.

Use Cases for Developers

1. Personal Logbook Server: Amateur radio operators who want full control over their data can run Cloudlog on a home server or Raspberry Pi, avoiding cloud‑based services.
2. Integrated DX Cluster: A dev can hook Cloudlog’s API into a DX cluster daemon to auto‑populate contacts as they are received.
3. Education Projects: In university radio clubs, students can learn PHP MVC patterns by extending Cloudlog’s hook system or adding new reporting modules.
4. Micro‑services: The API can serve as a micro