AI Builder — Technical Documentation

1. Project Overview

AI Builder is a personal developer productivity tool that combines the Claude API with a pre-wired server environment to generate, deploy, and manage complete PHP/MySQL web applications automatically. The developer describes what they want in plain language, and the system builds the entire application — database, config, auth, interfaces, modules — directly on the server within minutes.

2. Vision & Goals

3. Technology Stack

4. LXD Container

A single LXD container serves as the complete environment. Everything runs inside it — the web server, database, Python orchestrator, ttyd terminal, and all generated projects.

Container Contents

5. Server Layout

6. Subdomain System

Every new project automatically gets its own subdomain. This reuses your existing subdomain generation command, extended to be project-aware.

# When project "school_management" is created:
provision_new_project("school_management")

# Automatically triggers:
school_management.yourserver.com      # web access
terminal.school_management.yourserver.com  # ttyd terminal

Each project stores its domain info in .project_config.json inside the project folder.

7. Standard File Structure

8. Build Rules — What Gets Generated

9. Design Profile

Every project stores a .design_profile.json in its root folder. This is injected into every Claude request so all generated files are consistently styled.

{
  "theme": {
    "primary_color": "#1a73e8",
    "secondary_color": "#f4f4f4",
    "accent_color": "#ff5722"
  },
  "typography": {
    "font_family": "Poppins",
    "base_font_size": "15px",
    "heading_size": "24px"
  },
  "layout": {
    "sidebar_style": "dark",
    "navbar_style": "light",
    "card_style": "rounded"
  }
}

10. Coding Standards

11. Config Pattern

All projects use the Database singleton class pattern. One connection per request, shared cleanly across all 3 shell files.

class Database {
    private static $instance = null;
    private $connection;

    private function __construct() {
        $dsn = "mysql:host=DB_HOST;dbname=DB_NAME;charset=utf8mb4";
        $this->connection = new PDO($dsn, DB_USER, DB_PASS, [
            PDO::ATTR_ERRMODE            => PDO::ERRMODE_EXCEPTION,
            PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
            PDO::ATTR_EMULATE_PREPARES   => false
        ]);
    }

    public static function getInstance(): Database {
        if (self::$instance === null) {
            self::$instance = new Database();
        }
        return self::$instance;
    }

    public function getConnection(): PDO {
        return $this->connection;
    }
}

// Usage everywhere:
$db = Database::getInstance()->getConnection();

Standard Config Helper Functions — Always Present

12. Auth Pattern

Every role uses completely separate session variables. Admin and user can be logged in simultaneously without conflict. Each shell checks only its own session.

// user_auth.php — sets:
$_SESSION['user_logged_in'] = true;
$_SESSION['user_id']         = $user['id'];
$_SESSION['user_role']       = 'user';

// admin_auth.php — sets:
$_SESSION['admin_logged_in'] = true;
$_SESSION['admin_id']        = $admin['id'];
$_SESSION['admin_role']      = 'admin';

// receptionist_auth.php — sets:
$_SESSION['receptionist_logged_in'] = true;
$_SESSION['receptionist_id']        = $user['id'];
$_SESSION['receptionist_role']      = 'receptionist';

13. The 3-File Shell Pattern

Every primary interface splits into exactly 3 files. This allows quick customization of any part without touching the others.

14. Database Standards

15. Ajax Standard

Every ajax file follows an identical response structure. The frontend always knows exactly what to expect.

<?php
defined('APP_ACCESS') or die('Direct access not allowed');
header('Content-Type: application/json');

function ajax_response(bool $success, string $message, array $data = []): void {
    echo json_encode([
        'success' => $success,
        'message' => $message,
        'data'    => $data
    ]);
    exit;
}

// Success:
ajax_response(true, 'Payment initiated', ['ref' => $ref]);

// Error:
ajax_response(false, 'Invalid amount');

16. Error Handling

Every section file wraps all logic in try/catch. Development shows real errors, production shows safe messages.

try {
    // all database and logic operations
} catch (PDOException $e) {
    if (APP_ENV === 'development') {
        set_message($e->getMessage(), 'danger');
    } else {
        set_message('Database error. Please try again.', 'danger');
    }
} catch (Exception $e) {
    set_message($e->getMessage(), 'danger');
}

17. Security Standards

18. Python Orchestrator Architecture

The orchestrator is the central brain. It handles all decision-making so Claude receives only a fully baked package and does nothing but write code.

# orchestrator.py — main entry point
def handle_request(project_name, request_type, user_message):

    if request_type == 'build':
        from modules.builder import build_project
        return build_project(project_name, user_message)

    elif request_type == 'patch':
        from modules.patcher import patch_project
        return patch_project(project_name, user_message)

    elif request_type == 'rollback':
        from modules.backup import rollback
        return rollback(project_name)

    elif request_type == 'download':
        from modules.downloader import download_project
        return download_project(project_name)

19. Context Builder

The context builder assembles the complete package Claude receives. Claude never sees a raw request — it always receives fully baked context.

def build_context(project_name, current_file, existing_files, next_file, patch_history=None):

    context = {
        # Layer 1 — Infrastructure (never changes)
        "server_path":    f"/var/www/projects/{project_name}",
        "database_name":  project_name,
        "stack":          "PHP 8.x, Bootstrap 5, MySQL/MariaDB",
        "conventions":    load_conventions(),    # your full standards

        # Layer 2 — Project context
        "project_name":   project_name,
        "design_profile": load_design_profile(project_name),
        "existing_files": read_existing_files(project_name, existing_files),

        # Layer 3 — Current task
        "current_file":   current_file,
        "next_file":      next_file,
        "instruction":    f"Build ONLY {current_file}. Return complete file. No explanation.",

        # Layer 4 — Patch history (only during patching)
        "patch_history":  patch_history if patch_history else []
    }

    return context

20. Build Pipeline

Build File Order — Always Followed

21. Patch Pipeline

22. Validation & Auto-Fix

Every file is validated immediately after writing. Errors are automatically sent back to Claude for fixing before moving to the next file.

def validate_php_file(file_path):
    result = subprocess.run(['php', '-l', file_path], capture_output=True, text=True)
    if 'No syntax errors detected' in result.stdout:
        return {'valid': True}
    return {'valid': False, 'error': result.stdout + result.stderr}

def write_and_validate(file_path, content, context, attempt=1):
    MAX_ATTEMPTS = 3
    write_file(file_path, content)
    result = validate_php_file(file_path)

    if result['valid']:
        return True

    if attempt >= MAX_ATTEMPTS:
        notify_developer(f"Could not auto-fix {file_path}. Manual review needed.")
        return False

    # Send error back to Claude for fix
    fixed_content = send_fix_request(file_path, content, result['error'], context)
    return write_and_validate(file_path, fixed_content, context, attempt + 1)

def validate_http_response(subdomain):
    result = subprocess.run(
        ['curl', '-I', '-s', f'https://{subdomain}'],
        capture_output=True, text=True
    )
    status = result.stdout.split('\n')[0].split(' ')[1]
    return {'valid': status.startswith(('2', '3')), 'status': status}

23. Backup & Rollback

def backup_project(project_name):
    live   = f"/var/www/projects/{project_name}"
    backup = f"/var/www/projects/{project_name}_backup"

    # Delete previous backup
    if os.path.exists(backup):
        shutil.rmtree(backup)

    # Create fresh backup from live
    shutil.copytree(live, backup)
    return "backup_complete"

def rollback(project_name):
    live   = f"/var/www/projects/{project_name}"
    backup = f"/var/www/projects/{project_name}_backup"

    shutil.rmtree(live)                   # wipe broken version
    shutil.copytree(backup, live)          # restore backup
    log("Rollback complete")

Server always maintains exactly two copies — live + one latest backup. Nothing more, no disk bloat.

24. Token Management

The system builds file-by-file so token limits are never a crisis — they are a natural pause in a pipeline that always knows where it is.

# .build_state.json — tracked per project
{
  "project_id":   "hospital_system",
  "status":       "in_progress",       // "complete" | "paused" | "error"
  "completed":    ["database.sql", "config.php", "index.php"],
  "pending":      ["user_auth.php", "user_interface.php", "admin.php"],
  "current_file": "user_auth.php",
  "last_updated": "2026-01-04 10:23:00"
}

When tokens run out — Python saves exact state, notifies developer, waits. When developer clicks Continue, Python reads build state and resumes exactly where it stopped. Nothing repeated, nothing lost.

25. Claude API Integration

Claude receives a fully baked JSON package every request. It has zero decisions to make — it only writes code.

26. System Prompt Structure

You are a PHP developer working on a production server.

SERVER PATH:    /var/www/projects/{project_name}/
DATABASE:       {project_name} on localhost
STACK:          PHP 8.x, Bootstrap 5, MySQL/MariaDB
WEB SERVER:     Apache with mod_rewrite

CODING STANDARDS:
- CSS: always single line per rule
- Every section file starts with: defined('APP_ACCESS') or die(...)
- Database class: Database::getInstance()->getConnection()
- Auth: separate session variables per role
- CSRF: validate on every POST
- Output buffering: ob_start() top, ob_end_flush() bottom
- Error handling: try/catch always, set_message() for user feedback
- Ajax: always return ajax_response(success, message, data)
- Mobile: always consider responsive design

DESIGN PROFILE: {design_profile_json}

EXISTING FILES ALREADY BUILT:
{existing_file_contents}

YOUR TASK:
Build ONLY this file: {current_file}
Next file after this: {next_file}

RULES:
- Return ONLY the complete file content
- No explanation, no commentary, no markdown
- Stay consistent with existing files above
- Follow all coding standards above exactly

27. Structured Output Format

Claude is instructed to return structured JSON so Python can parse and execute reliably.

{
  "file":    "user_auth.php",
  "content": "<?php\nob_start();\ndefined('APP_ACCESS')...",
  "sql":     [],          // SQL statements if any (database.sql only)
  "notes":   ""           // optional: anything Python should know
}

28. API Key Storage

The Claude API key is stored in the system_settings table. Change it from the UI — no file editing ever.

-- system_settings table
INSERT INTO system_settings (setting_key, setting_value, is_encrypted)
VALUES ('claude_api_key', 'your-key-here', 1);

-- Retrieved and cached in config.php:
function get_setting(string $key): string {
    static $settings = [];
    if (!isset($settings[$key])) {
        $db = Database::getInstance()->getConnection();
        $stmt = $db->prepare("SELECT setting_value FROM system_settings WHERE setting_key = :key");
        $stmt->execute([':key' => $key]);
        $settings[$key] = $stmt->fetchColumn() ?? '';
    }
    return $settings[$key];
}

29. Project Management

Every project is a folder. The folder name is everything — it tells Python and Claude which project is active.

Project Config — .project_config.json

{
  "project_name":  "hospital_system",
  "created_at":    "2026-01-04",
  "subdomain":     "hospital_system.yourserver.com",
  "ttyd":          "terminal.hospital_system.yourserver.com",
  "project_path":  "/var/www/projects/hospital_system",
  "project_type":  "full_system",
  "status":        "live"
}

Three Ways A Project Starts

30. Upload Existing Projects

Any project built previously — even manually — becomes Claude-editable immediately after upload, as long as it follows the standard structure.

def validate_structure(uploaded_files):
    standard = [
        'database.sql', 'config.php', 'index.php',
        'user_auth.php', 'user_interface.php',
        'admin_auth.php', 'admin.php'
    ]
    found   = [f for f in standard if f in uploaded_files]
    missing = [f for f in standard if f not in uploaded_files]
    custom  = [f for f in uploaded_files if f not in standard]
    return found, missing, custom  # custom files accepted regardless

31. Download as ZIP

Every project can be downloaded as a clean ZIP with files in the correct order. Database first, config second, then everything else.

hospital_system.zip
├── database.sql          # always first
├── config.php            # always second
├── .htaccess
├── 404.php / 403.php / 500.php
├── index.php
├── user_auth.php
├── user_interface.php
├── user_header.php / user_sidebar.php
├── admin_auth.php
├── admin.php
├── admin_header.php / admin_sidebar.php
├── usersections/
├── adminsections/
├── integrations/
├── ajax/
└── assets/

32. Build State Tracking

Python maintains a build state file per project. If tokens run out mid-build, the state is saved and the build resumes exactly where it stopped on next run.

33. Patch History

Every patch is logged. Old versions are never deleted. Rollback is always one click away.

-- patch_history table tracks every change
patch_history (
    id               INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    project_id       VARCHAR(100)  NOT NULL,
    file_path        VARCHAR(255)  NOT NULL,
    patch_description TEXT         NOT NULL,  -- what was requested
    content_before   LONGTEXT      NOT NULL,  -- full file before patch
    content_after    LONGTEXT      NOT NULL,  -- full file after patch
    version_number   INT UNSIGNED  NOT NULL,
    status           ENUM('applied','rolled_back') DEFAULT 'applied',
    patched_at       TIMESTAMP     NOT NULL DEFAULT CURRENT_TIMESTAMP
)

34. Builder Database Schema

CREATE TABLE projects (
    id           INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    project_name VARCHAR(100) NOT NULL UNIQUE,
    project_type ENUM('landing','user_only','admin_only','full_system') NOT NULL,
    status       ENUM('building','paused','live','error') DEFAULT 'building',
    subdomain    VARCHAR(255),
    ttyd_url     VARCHAR(255),
    created_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

CREATE TABLE project_files (
    id             INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    project_id     INT UNSIGNED NOT NULL,
    file_path      VARCHAR(255) NOT NULL,
    version_number INT UNSIGNED NOT NULL DEFAULT 1,
    last_updated   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
);

CREATE TABLE patch_history (
    id                INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    project_id        INT UNSIGNED NOT NULL,
    file_path         VARCHAR(255) NOT NULL,
    patch_description TEXT NOT NULL,
    content_before    LONGTEXT NOT NULL,
    content_after     LONGTEXT NOT NULL,
    version_number    INT UNSIGNED NOT NULL,
    status            ENUM('applied','rolled_back') DEFAULT 'applied',
    patched_at        TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
);

CREATE TABLE build_logs (
    id           INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    project_id   INT UNSIGNED NOT NULL,
    file_path    VARCHAR(255),
    action       ENUM('build','validate','fix','patch','rollback','error'),
    status       ENUM('pass','fail','fixed'),
    message      TEXT,
    created_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (project_id) REFERENCES projects(id) ON DELETE CASCADE
);

CREATE TABLE system_settings (
    id            INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    setting_key   VARCHAR(100) NOT NULL UNIQUE,
    setting_value TEXT NOT NULL,
    is_encrypted  TINYINT(1) NOT NULL DEFAULT 0,
    updated_at    TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

INSERT INTO system_settings (setting_key, setting_value, is_encrypted)
VALUES
  ('claude_api_key', 'YOUR_KEY_HERE', 1),
  ('claude_model',   'claude-sonnet-4-20250514', 0),
  ('max_fix_attempts', '3', 0),
  ('app_env',         'development', 0);

35. Builder UI Panels

36. Builder Sidebar Navigation

🏠  Dashboard
────────────────────
⚡  Create App         (chat ui — fresh build)
✏️   Edit App           (chat ui — patch existing)
────────────────────
📁  Projects
🌐  Connect Domain
────────────────────
📊  Build History
🔄  Patch History
────────────────────
🎨  Design Profiles
⚙️   Settings
────────────────────
📖  Documentation
────────────────────
💰  Token Usage
────────────────────
🚪  Logout

37. End-to-End Journey

AI Builder Technical Documentation v1.0  ·  All standards and conventions locked  ·  Ready to build