# toxichome-whoami/binary_alive architecture

> Architecture diagram of the GitHub repository toxichome-whoami/binary_alive, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/toxichome-whoami/binary_alive
- Repository: https://github.com/toxichome-whoami/binary_alive

## Overview

#### Purpose and Deployment Model
Secure Binary Alive System is a PHP 7.4+ / SQLite control plane for keeping Linux executables alive on cPanel/WHM hosts. It manages arbitrary binaries (bots, Node applications, compiled programs), exposes browser and token APIs, and relies on a host cron invocation rather than a persistent PHP daemon.

Core deployment/security boundaries are Apache access rules in `.htaccess`, `db/.htaccess`, `includes/.htaccess`, and `components/.htaccess`; cron must execute `cron.php` once per minute.

#### Web Application Entry Points
`index.php` is the dashboard and likely primary process-management surface. Authentication lifecycle is handled through `login.php`, `logout.php`, and initial TOTP enrollment in `setup_2fa.php`.

Administrative pages include `settings.php` for system/security configuration, `users.php` for role-managed accounts, `logs.php` for audit-log viewing, and `terminal.php` for the admin browser shell. Shared UI composition is centralized in `components/header.php`, `components/navbar.php`, and `components/footer.php`.

#### Process Supervision Stage
`cron.php` is the autonomous supervision entry point. Each minute it evaluates configured monitored processes, detects stopped binaries or reboot-related loss, and restarts them. This is the critical boundary between the PHP application and operating-system process execution.

Interactive UI management and remote control can initiate start, stop, restart, creation, editing, deletion, and grouping of monitored processes; cron converges actual process state with the stored desired configuration.

#### Persistence and Configuration
SQLite access and schema/runtime persistence are centralized in `includes/database.php`, with the database protected beneath `db/`. Persistent records support users/roles, process definitions, audit events, API tokens, and application state.

`config.json` supplies deployment-level settings, notably IP allowlisting. This file is intentionally web-blocked by root `.htaccess`; it is a filesystem configuration boundary rather than an API-facing resource.

#### Identity, Authorization, and Security
`includes/auth.php` implements session authentication and RBAC, including the permanent first-account Master Admin hierarchy. Admin privileges gate sensitive operations such as account administration and terminal access.

`includes/security.php` provides request/security controls such as IP restrictions and headers. CAPTCHA is a separate challenge/check flow in `captcha.php` and `captcha_check.php`. TOTP/2FA behavior is supported by `includes/totp_helper.php` and exposed through `setup_2fa.php`.

#### API and External Control Boundary
`api.php` is the machine-facing entry point for remote process monitoring and control using API tokens. Its contract is documented in `API.md`. API actions share the same persistence, authorization/token validation, process-control, and audit pathways as browser actions.

There are no required external application services: runtime dependencies are PHP, SQLite, Apache/cPanel, Linux shell/process facilities, and cPanel cron.

#### Auditability and Shell Access
`includes/logger.php` records security- and operations-relevant events: authentication attempts, process lifecycle actions, terminal commands, and API key generation. `logs.php` exposes paginated audit history.

`terminal.php` is a high-risk administrative boundary: it runs server shell commands with a session-persistent working directory, command history, and a 30-second timeout guard. It must remain constrained by admin RBAC and audited through the logging layer.

Main entry points: [`includes/auth.php`](https://github.com/toxichome-whoami/binary_alive/blob/main/includes/auth.php) (Session auth & RBAC), [`settings.php`](https://github.com/toxichome-whoami/binary_alive/blob/main/settings.php) (Admin pages), [`api.php`](https://github.com/toxichome-whoami/binary_alive/blob/main/api.php) (Token API), [`includes/logger.php`](https://github.com/toxichome-whoami/binary_alive/blob/main/includes/logger.php) (Audit logger)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web & API"]
  node_dashboard["Dashboard<br/>browser UI<br/>[index.php]"]
  node_auth_pages["Auth lifecycle<br/>browser UI<br/>[login.php]"]
  node_admin_pages["Admin pages<br/>browser UI<br/>[settings.php]"]
  node_api["Token API<br/>HTTP API<br/>[api.php]"]
  node_api_docs["API contract<br/>documentation<br/>[API.md]"]
  node_access_rules{{"Apache access rules<br/>security boundary<br/>[.htaccess]"}}
end

subgraph group_core["Application Core"]
  node_auth["Session auth &amp; RBAC<br/>identity service<br/>[auth.php]"]
  node_security["Request security<br/>security service<br/>[security.php]"]
  node_totp["TOTP support<br/>2FA service<br/>[totp_helper.php]"]
  node_captcha["CAPTCHA flow<br/>challenge endpoint<br/>[captcha.php]"]
  node_process_control["Process control<br/>control service"]
  node_logger["Audit logger<br/>audit service<br/>[logger.php]"]
  node_database[("SQLite persistence<br/>database access<br/>[database.php]")]
  node_config["Deployment config<br/>filesystem config<br/>[config.json]"]
end

subgraph group_host["Host Runtime"]
  node_cron{{"Minute supervisor<br/>cron entry point<br/>[cron.php]"}}
  node_linux(("Linux processes<br/>OS process runtime"))
end

node_dashboard -->|"session auth"| node_auth
node_dashboard -->|"protected requests"| node_security
node_dashboard -->|"manage processes"| node_process_control
node_auth_pages -->|"authenticate"| node_auth
node_auth_pages -->|"enroll 2FA"| node_totp
node_auth_pages -->|"challenge"| node_captcha
node_admin_pages -->|"admin RBAC"| node_auth
node_admin_pages -->|"view audit history"| node_logger
node_admin_pages -->|"admin shell commands"| node_linux
node_api -->|"validate API token"| node_auth
node_api -->|"remote control"| node_process_control
node_api -->|"audit actions"| node_logger
node_api_docs -.->|"documents"| node_api
node_security -->|"IP allowlist"| node_config
node_auth -->|"users and tokens"| node_database
node_process_control -->|"desired definitions"| node_database
node_process_control -->|"start / stop / restart"| node_linux
node_logger -->|"audit events"| node_database
node_cron -->|"read desired state"| node_database
node_cron -->|"detect and restart"| node_linux
node_admin_pages -->|"terminal audit"| node_logger
node_access_rules -.->|"web-blocked"| node_config

click node_dashboard "https://github.com/toxichome-whoami/binary_alive/blob/main/index.php"
click node_auth_pages "https://github.com/toxichome-whoami/binary_alive/blob/main/login.php"
click node_admin_pages "https://github.com/toxichome-whoami/binary_alive/blob/main/settings.php"
click node_api "https://github.com/toxichome-whoami/binary_alive/blob/main/api.php"
click node_api_docs "https://github.com/toxichome-whoami/binary_alive/blob/main/API.md"
click node_access_rules "https://github.com/toxichome-whoami/binary_alive/blob/main/.htaccess"
click node_auth "https://github.com/toxichome-whoami/binary_alive/blob/main/includes/auth.php"
click node_security "https://github.com/toxichome-whoami/binary_alive/blob/main/includes/security.php"
click node_totp "https://github.com/toxichome-whoami/binary_alive/blob/main/includes/totp_helper.php"
click node_captcha "https://github.com/toxichome-whoami/binary_alive/blob/main/captcha.php"
click node_logger "https://github.com/toxichome-whoami/binary_alive/blob/main/includes/logger.php"
click node_database "https://github.com/toxichome-whoami/binary_alive/blob/main/includes/database.php"
click node_config "https://github.com/toxichome-whoami/binary_alive/blob/main/config.json"
click node_cron "https://github.com/toxichome-whoami/binary_alive/blob/main/cron.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dashboard,node_auth_pages,node_admin_pages,node_api,node_api_docs,node_access_rules toneBlue
class node_auth,node_security,node_totp,node_captcha,node_process_control,node_logger,node_database,node_config toneAmber
class node_cron,node_linux toneMint
```

## Components

### Web & API

- [Dashboard](https://github.com/toxichome-whoami/binary_alive/blob/main/index.php): browser UI · Primary process-management surface. · `index.php`
- [Auth lifecycle](https://github.com/toxichome-whoami/binary_alive/blob/main/login.php): browser UI · Login, logout, and initial 2FA enrollment. · `login.php`
- [Admin pages](https://github.com/toxichome-whoami/binary_alive/blob/main/settings.php): browser UI · Settings, users, logs, and terminal access. · `settings.php`
- [Token API](https://github.com/toxichome-whoami/binary_alive/blob/main/api.php): HTTP API · Remote process monitoring and control entry point. · `api.php`
- [API contract](https://github.com/toxichome-whoami/binary_alive/blob/main/API.md): documentation · `API.md`
- [Apache access rules](https://github.com/toxichome-whoami/binary_alive/blob/main/.htaccess): security boundary · Blocks protected application, database, and configuration resources. · `.htaccess`

### Application Core

- [Session auth & RBAC](https://github.com/toxichome-whoami/binary_alive/blob/main/includes/auth.php): identity service · Enforces roles, including the Master Admin hierarchy. · `includes/auth.php`
- [Request security](https://github.com/toxichome-whoami/binary_alive/blob/main/includes/security.php): security service · Applies IP restrictions and security headers. · `includes/security.php`
- [TOTP support](https://github.com/toxichome-whoami/binary_alive/blob/main/includes/totp_helper.php): 2FA service · `includes/totp_helper.php`
- [CAPTCHA flow](https://github.com/toxichome-whoami/binary_alive/blob/main/captcha.php): challenge endpoint · `captcha.php`
- **Process control**: control service · Changes desired state for monitored binaries.
- [Audit logger](https://github.com/toxichome-whoami/binary_alive/blob/main/includes/logger.php): audit service · Records authentication, process, terminal, and API events. · `includes/logger.php`
- [SQLite persistence](https://github.com/toxichome-whoami/binary_alive/blob/main/includes/database.php): database access · Stores users, process definitions, tokens, audit events, and state. · `includes/database.php`
- [Deployment config](https://github.com/toxichome-whoami/binary_alive/blob/main/config.json): filesystem config · Provides settings including IP allowlisting. · `config.json`

### Host Runtime

- [Minute supervisor](https://github.com/toxichome-whoami/binary_alive/blob/main/cron.php): cron entry point · Converges configured process state and restarts stopped binaries. · `cron.php`
- **Linux processes**: OS process runtime · Executes and hosts monitored binaries and terminal commands.

## Connections

- Dashboard → Session auth & RBAC: session auth
- Dashboard → Request security: protected requests
- Dashboard → Process control: manage processes
- Auth lifecycle → Session auth & RBAC: authenticate
- Auth lifecycle → TOTP support: enroll 2FA
- Auth lifecycle → CAPTCHA flow: challenge
- Admin pages → Session auth & RBAC: admin RBAC
- Admin pages → Audit logger: view audit history
- Admin pages → Linux processes: admin shell commands
- Token API → Session auth & RBAC: validate API token
- Token API → Process control: remote control
- Token API → Audit logger: audit actions
- API contract → Token API: documents
- Request security → Deployment config: IP allowlist
- Session auth & RBAC → SQLite persistence: users and tokens
- Process control → SQLite persistence: desired definitions
- Process control → Linux processes: start / stop / restart
- Audit logger → SQLite persistence: audit events
- Minute supervisor → SQLite persistence: read desired state
- Minute supervisor → Linux processes: detect and restart
- Admin pages → Audit logger: terminal audit
- Apache access rules → Deployment config: web-blocked