README

Agent Control PHP Application

Documentation Status

Overview

A PHP application to control agents from Google Jules, coordinated by GitHub repositories and issues. It provides a centralized platform for managing AI agent workflows through a unified web interface.

Architecture

Architecture

Top level ERD

Top level ERD

Database Schema

Database Schema

Task Lifecycle

Task States

Used APIs and Interfaces

Production

API / Interface

Description

Google SSO

Secure user authentication and session management.

GitHub REST API

Management of repositories, issues, and webhooks.

Google Jules API

Orchestration and control of AI agents.

PHP

Server-side scripting language for backend logic.

MySQL

Relational database for storing user and project data.

Tailwind CSS

Utility-first CSS framework for responsive UI design.

Alpine.js

Minimal framework for composing JavaScript behavior.

Guzzle

PHP HTTP client for sending API requests.

GitHub PHP API

Object-oriented wrapper for the GitHub API.

Telegram Bot API

Mobile-based agent control and notifications.
Test/Documentation

API / Interface

Description

PlantUML

Architecture diagram generation from text.

Agent Control API

OpenAPI 3.0 specification rendered with Redocly.

Features

Category

Feature

Description

Authentication & Security

Google SSO

Secure user authentication and session management.

Authentication & Security

Role-Based Access Control (RBAC)

Fine-grained permissions for administrators and regular users.

Authentication & Security

Security Hardening

Integrated CSRF protection and IP-based rate limiting for sensitive endpoints.

GitHub Integration

Multi-Account Support

Link and manage multiple GitHub accounts per application user.

GitHub Integration

Repository Synchronization

Seamlessly link repositories and synchronize issues as actionable tasks.

GitHub Integration

Automated Webhooks

Real-time updates for issue events (opened, edited, reopened) via secure webhooks.

GitHub Integration

Customizable Templates

Create and manage reusable GitHub issue templates with dynamic parameter support.

Agent Orchestration

Google Jules (Gemini) Integration

Power agent workflows using advanced AI models.

Agent Orchestration

Task Management

Track agent activity, execution logs, and status updates directly in the dashboard.

Agent Orchestration

Automated Feedback

Agents can post responses and status updates back to GitHub issues as comments.

Telegram Connectivity

Mobile Control

Interact with agents and receive status notifications via a dedicated Telegram Bot.

Telegram Connectivity

Secure Webhooks

Robust webhook handling with secret token validation.

Telegram Connectivity

Asynchronous Processing

Optimized response times using fast-cgi finish request for immediate acknowledgement.

Developer Experience

CI/CD Pipeline

Automated testing (PHPUnit, Playwright) and documentation builds via GitHub Actions.

Developer Experience

Comprehensive Documentation

Integrated Sphinx documentation (Read the Docs) and OpenAPI 3.0 specification.

Getting Started

Requirements

  • PHP 8.3+

  • MySQL

  • Composer

Installation

See the Installation Guide for detailed instructions on how to install the PHP backend and legacy UI.

For the new React-based interface, see the Next-Gen UI Installation Guide.

For quick local installation:

  1. Clone the repository.

  2. Install dependencies:

    ./src/install.sh

  3. Set up your environment variables (DB_HOST, DB_NAME, DB_USER, DB_PASS, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REDIRECT_URI).

  4. Initialize the database using src/sql/schema.sql.

Local Development

Start the local development server:

php -S localhost:8080 -t src/frontend

Project Structure

  • src/frontend/: Web entry points (index.php, google/login.php, etc.) and frontend assets.

  • src/backend/: Core PHP logic and classes.

  • src/sql/: Database schema and migrations.

  • test/: PHPUnit tests and testing tools.

  • specification/: Additional documentation, mockups, and external know-how.

  • TOP_CONCEPT.md, TOP_DESIGN.md, GEMINI.md, TOP_ROADMAP.md, NOTIF_ROADMAP.md, CHAT_ROADMAP.md: Project documentation.

Documentation