ko_center System Administrator Documentation

1. System Architecture & Design

1.1 Architectural Overview

ko_center is a single-file PHP web application — all 205 functions and the entire routing logic reside in one file. It follows a traditional LAMP stack pattern with no external framework dependencies.

1.2 Request Lifecycle

HTTP Request → Apache/PHP → startup() → Parse ?q= → Route to handler → Generate HTML → Response

startup() does:
  1. session_start()
  2. Set error_reporting(0)
  3. Initialize $progid, $dttm, $dttm_ip
  4. Set $GLOBALS paths (dbfile, kbfile, hosts_allow, logfil, etc.)
  5. Detect host OS (win/linux)
  6. Parse $_REQUEST['q'] into $options[] array
  7. Check if database exists (auto-install if not)
  8. Route to appropriate handler based on $options[0]

1.3 Core Global Variables

1.4 $GLOBALS Registry

2. Installation & Initial Setup

2.1 Prerequisites

2.2 Installation Steps

mkdir -p /var/www/html/ko_center
mkdir -p /var/www/html/ko_center/db3
mkdir -p /var/www/html/ko_center/kb
mkdir -p /var/www/html/ko_center/images/btn
mkdir -p /var/www/html/ko_center/images/ani
mkdir -p /var/www/html/ko_center/images/fpb
cp ko_center.php /var/www/html/ko_center/
cp ko_center.db3 /var/www/html/ko_center/db3/

allow all
# Format: allow <user> <role> <username>
# Example: allow admin user joachim

chown -R www-data:www-data /var/www/html/ko_center/
chmod 666 /var/www/html/ko_center/db3/ko_center.db3
chmod 755 /var/www/html/ko_center/
chmod 666 /var/www/html/ko_center/ko_trigger.dat  # if using trigger feature

http://<server>/ko_center/ko_center.php

2.3 leds_install() Function Details

The leds_install() function (line 9707) supports two modes:

Tables created during install:

3. Configuration Reference

3.1 Path Configuration (startup() lines 130-151)

3.2 Theme Configuration

Available jQuery UI themes (set via $_SESSION['theme']):

3.3 Session Variables

4. Database Administration

4.1 Database File

4.2 Database Connection Function

function newpdo( $dbfile ) {
    $pdo = new PDO("sqlite:$dbfile");
    $pdo->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $pdo->setAttribute(PDO::ATTR_DEFAULT_FETCH_MODE, PDO::FETCH_ASSOC);
    return $pdo;
}

4.3 Complete Table Inventory

4.4 Database Maintenance Commands

# Integrity check
sqlite3 /os/ai/io/ko_center.db3 "PRAGMA integrity_check;"

# List all tables
sqlite3 /os/ai/io/ko_center.db3 ".tables"

# Row counts for all tables
sqlite3 /os/ai/io/ko_center.db3 "SELECT name, (SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name=m.name) FROM sqlite_master m WHERE type='table';"

# Vacuum (reclaim space, rebuild database)
sqlite3 /os/ai/io/ko_center.db3 "VACUUM;"

# Analyze (update query planner statistics)
sqlite3 /os/ai/io/ko_center.db3 "ANALYZE;"

# Backup
cp /os/ai/io/ko_center.db3 /os/ai/io/ko_center.db3.backup.$(date +%Y%m%d_%H%M%S)

# Export table to CSV
sqlite3 -header -csv /os/ai/io/ko_center.db3 "SELECT * FROM leds LIMIT 100;" > leds_export.csv

# Check database size
ls -lh /os/ai/io/ko_center.db3

# Check freelist (fragmentation indicator)
sqlite3 /os/ai/io/ko_center.db3 "PRAGMA freelist_count;"

5. User & Role Management

5.1 Authentication Flow

1. User accesses application → leds_login_form() (line 8450) displays login form
2. User submits credentials → leds_login_validate() (line 8568) processes
3. Credentials validated against hosts.allow file contents
4. On success: $_SESSION['user'] and $_SESSION['role'] are set
5. On failure: Login form redisplayed with error
6. Logout: leds_logout() (line 8739) clears session and redirects

5.2 Role Definitions

5.3 Role-Based Database Access

The dbs_init() function (line 15441) defines multi-database access by role:

$dbfiles['admin']['ko_center']['dbfile'] = "$document_root/ko_center/ko_center.db3";
$dbfiles['admin']['ko_center']['tables'] = array('fp', 'leds', 'rpts', 'roles', 'users', ...);

Each role has access to specific databases and tables, enabling data isolation between user groups.

6. Security Assessment

6.1 Vulnerability Summary

6.2 Recommended Remediations

7. Logging, Debugging & Monitoring

7.1 Log File Configuration

Log files are created in the ko_safer directory with monthly rotation:

Log directory: /os/ai/io/../ko_safer/
Log pattern:  ko_center_YYYYMM.log
Example:      /os/ai/io/../ko_safer/ko_center_202608.log

Log file path construction (startup() lines 144-148):

$yyyymm = date('Ym');
$logfil_basename = $progid . "_" . $yyyymm . ".log";
$logfil_rootpath = $document_root . "/../ko_safer";
$logfil = $logfil_rootpath . "/" . $logfil_basename;
$GLOBALS['logfil'] = $logfil;

7.2 Logging Functions

7.3 Debug Mode

Debug output is currently disabled (error_reporting(0) at line 107). To enable debugging:

1. Change error_reporting(0) to error_reporting(E_ALL) in startup()
2. Uncomment debug print() statements throughout the code (prefixed with //)
3. Check log files in /os/ai/io/../ko_safer/
4. Use ?q=about or ?q=pdo for basic diagnostics

7.4 Monitoring Checklist

• Monitor disk space: df -h /os/ai/io/
• Monitor log file sizes: ls -lh /os/ai/io/../ko_safer/
• Monitor database file size: ls -lh /os/ai/io/ko_center.db3
• Check web server error log: tail -f /var/log/apache2/error.log
• Verify database integrity weekly: sqlite3 ko_center.db3 "PRAGMA integrity_check;"

8. Backup & Recovery Procedures

8.1 Backup Script

#!/bin/bash
# ko_center_backup.sh — Daily backup script

DB="/os/ai/io/ko_center.db3"
KB="/os/ai/io/ko_center/kb"
CERTS="/os/ai/io/ko_center/db3/ko_center_certs.db3"
KB_DB="/os/ai/io/ko_center/db3/koaac_kb.db3"
BACKUP_DIR="/os/ai/io/backups"
HOSTS_ALLOW="/os/ai/io/../safer/hosts.allow"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p "$BACKUP_DIR"

# Backup database
cp "$DB" "$BACKUP_DIR/ko_center_$DATE.db3"
gzip "$BACKUP_DIR/ko_center_$DATE.db3"

# Backup certificates DB
cp "$CERTS" "$BACKUP_DIR/ko_center_certs_$DATE.db3"
gzip "$BACKUP_DIR/ko_center_certs_$DATE.db3"

# Backup KB database
cp "$KB_DB" "$BACKUP_DIR/koaac_kb_$DATE.db3"
gzip "$BACKUP_DIR/koaac_kb_$DATE.db3"

# Backup hosts.allow
cp "$HOSTS_ALLOW" "$BACKUP_DIR/hosts.allow_$DATE"

# Backup KB file attachments
tar -czf "$BACKUP_DIR/ko_kb_attachments_$DATE.tar.gz" -C "$(dirname $KB)" "$(basename $KB)"

# Keep only last 30 days of backups
find "$BACKUP_DIR" -name "ko_center_*.db3.gz" -mtime +30 -delete
find "$BACKUP_DIR" -name "hosts.allow_*" -mtime +30 -delete
find "$BACKUP_DIR" -name "ko_kb_attachments_*.tar.gz" -mtime +30 -delete

echo "Backup completed: $DATE"

8.2 Recovery Procedure

1. Stop the web server: systemctl stop apache2 (or service apache2 stop)
2. Copy backup to database location:

   gunzip -c /os/ai/io/backups/ko_center_YYYYMMDD_HHMMSS.db3.gz > /os/ai/io/ko_center.db3

3. Verify integrity:

   sqlite3 /os/ai/io/ko_center.db3 "PRAGMA integrity_check;"

4. Set correct permissions:

   chown www-data:www-data /os/ai/io/ko_center.db3
   chmod 666 /os/ai/io/ko_center.db3

5. Start the web server: systemctl start apache2
6. Verify: Browse to ?q=about and ?q=pdo

8.3 Files to Backup

9. Routine Maintenance

9.1 Scheduled Maintenance Tasks

9.2 LED Record Management

LED records use led_dttm = 'current' to mark active records. Historical records should be archived:

-- Archive old LED records to a separate table
CREATE TABLE IF NOT EXISTS leds_archive AS SELECT * FROM leds WHERE 1=0;
INSERT INTO leds_archive SELECT * FROM leds WHERE led_dttm != 'current';
DELETE FROM leds WHERE led_dttm != 'current';

9.3 Database Optimization

# Rebuild all indexes
sqlite3 /os/ai/io/ko_center.db3 "REINDEX;"

# Update query planner statistics
sqlite3 /os/ai/io/ko_center.db3 "ANALYZE;"

# Check database size
ls -lh /os/ai/io/ko_center.db3

# Check for fragmentation
sqlite3 /os/ai/io/ko_center.db3 "PRAGMA freelist_count;"

# If freelist_count > 0, vacuum is recommended
sqlite3 /os/ai/io/ko_center.db3 "VACUUM;"

10. Troubleshooting Guide

10.1 Common Issues & Solutions

10.2 Debugging Checklist

1. Check PHP is running: php -v
2. Check database exists: ls -la /os/ai/io/ko_center.db3
3. Check database integrity: sqlite3 /os/ai/io/ko_center.db3 "PRAGMA integrity_check;"
4. Check web server error log: tail -f /var/log/apache2/error.log
5. Check application logs: ls -la /os/ai/io/../ko_safer/
6. Verify file permissions: namei -l /os/ai/io/ko_center.db3
7. Test basic functionality: Browse to ?q=about
8. Test database connectivity: Browse to ?q=pdo
9. Check PHP error log: tail -f /var/log/php_errors.log
10. Enable error reporting: Temporarily set error_reporting(E_ALL) in startup()

10.3 Performance Tuning

11. File Structure & Asset Inventory

11.1 Complete Directory Layout

/os/ai/io/
├── ko_center.php          [16,322 lines]  Main PHP application
├── ko_center.py            [Python Flask]  Python equivalent
├── ko_center.db3           [39.6 MB]      SQLite database
├── ko_center.html          [User doc]      System user documentation
├── ko_center_admin.html    [Admin doc]     Administrator documentation (previous)
├── ko_center_sysadm.html   [This file]    System administrator documentation
├── new_leds.py             [Script]       Create leds_randomus table
├── new_leds_tbl.py         [Script]       Generalized table creation
├── cr_leds.py              [Script]       LED GIF generation with ImageMagick
├── response_trigger_plan.txt       [Doc]    Trigger mechanism design
├── prompt_*.txt            [Prompts]      Original task prompts
├── response_*.txt          [Docs]         Response documents
├── ko_trigger.dat          [Runtime]      Trigger timestamp (created at runtime)
├── led_red_flashing.jpg    [Asset]        LED image asset
├── images/
│   ├── btn/                 Button GIF images (btn_black.gif, btn_white.gif, etc.)
│   ├── ani/                 Animated LED GIFs (ani_red0.gif through ani_trans3.gif)
│   ├── fpb/                 Floor plan button images
│   └── cab/                 Cabinet images
├── ko_center/
│   ├── db3/                 Additional database files
│   │   ├── ko_center_certs.db3
│   │   └── koaac_kb.db3
│   └── kb/                  Knowledge Base file storage
├── js/
│   ├── jquery-1.7.2.min.js
│   ├── jquery-ui-1.7.2.custom.min.js
│   ├── fg-menu/             fg-menu JavaScript and CSS
│   ├── jqgrid-4.4.0/       jqGrid library (JS, CSS, images, i18n)
│   └── tooltip/             Tooltip JavaScript
├── css/                     Theme CSS files (jQuery UI themes)
├── ../safer/
│   └── hosts.allow          Authentication/authorization file
└── ../ko_safer/
    └── ko_center_YYYYMM.log  Monthly application logs

11.2 Key File Sizes

12. PHP Function Reference (205 Functions)

12.1 Core Application Functions

12.2 Database Functions

12.3 Grid & Data Display Functions

12.4 Report Functions

12.5 KB (Knowledge Base) Functions

12.6 Utility Functions

12.7 AJAX Functions

12.8 View/Page Functions

12.9 Special-Purpose Functions

13. Deployment & Server Configuration

13.1 Apache Virtual Host Configuration

<VirtualHost *:80>
    ServerName ko_center.example.com
    DocumentRoot /os/ai/io

    <Directory /os/ai/io>
        Options +FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    # PHP configuration
    php_value upload_max_filesize 50M
    php_value post_max_size 50M
    php_value max_execution_time 300
    php_value memory_limit 256M

    # SQLite configuration
    php_value sqlite.assoc_case 0

    # Logging
    ErrorLog /var/log/apache2/ko_center_error.log
    CustomLog /var/log/apache2/ko_center_access.log combined

    # Security headers
    Header set X-Content-Type-Options "nosniff"
    Header set X-Frame-Options "SAMEORIGIN"
</VirtualHost>

13.2 Environment Variables

13.3 PHP Configuration Recommendations

; php.ini or .htaccess settings for ko_center

memory_limit = 256M
max_execution_time = 300
upload_max_filesize = 50M
post_max_size = 50M

; SQLite
sqlite3.extension_dir = ""

; Session
session.gc_maxlifetime = 1440
session.cookie_httponly = 1
session.cookie_samesite = "Lax"

; Error reporting (production)
display_errors = Off
log_errors = On
error_log = /var/log/php_errors.log

14. Python Flask Equivalent

A Python Flask equivalent of ko_center.php has been created at /os/ai/io/ko_center.py. Key differences:

Running the Python version:

python3 /os/ai/io/ko_center.py

Then browse to http://localhost:5000

15. API & URL Routing Reference

15.1 Complete Route Reference

15.2 Trigger API

The trigger endpoint provides a JSON API for browser refresh coordination across multiple clients:

Request

GET /ko_center/ko_center.php?q=trigger[&last_check=<timestamp>]

Response

{
  "triggered": true|false,
  "timestamp": "2026-08-01 07:05:00",
  "since": "2026-08-01 07:00:00"
}

Workflow

1. Browser A polls ?q=trigger every 3 seconds
2. Browser B calls ?q=trigger (writes timestamp to ko_trigger.dat)
3. Browser A's next poll detects the new timestamp
4. Browser A calls window.location.reload()

16. Version History