uce/site/examples/web-app-starter/.ai/instructions.md

Web App Starter - AI Assistant Instructions

Project Architecture

Custom PHP framework with server-side rendering focus, component-based UI, and clean URL routing.

Core Flow

1. index.php → URL::MakeRoute() → views/{page}.php → theme template
2. All requests flow through index.php (single entry point)
3. Views render into URL::$fragments['main'], then wrapped by theme

Key Directories

• lib/ - Core classes (URL, DB, Log, Profiler, components)
• views/ - Page templates (maps to URL routes)
• components/ - Reusable UI components
• config/settings.php - Main configuration
• themes/ - Page layout templates
• js/ - Client-side code (uquery.js, morphdom.js, etc.)

Core Classes & Functions

Configuration

cfg('key/path')           // Get config value
cfg('url/pretty')         // true=clean URLs, false=query strings

URL Routing

URL::MakeRoute()          // Parse URL into URL::$route
URL::Link($path, $params) // Generate URLs (respects pretty URL setting)
URL::$route['page']       // Target view (default: 'index')
URL::$route['l-path']     // Full URL path
URL::$fragments['main']   // Main content area

Components

Files return arrays with render functions:

<?php return [
    'render' => function($prop) { return '<div>...</div>'; },
    'about' => 'Component description'
];

Usage:

component('path/to/component', ['prop' => 'value'])
component('path/to/component:method', $props)  // Specific render method
component_declare('name', $definition)        // Inline declaration

Database

DB::Query($sql, $params)            // Execute any SQL query
DB::Get($sql, $params)              // Get multiple rows as array
DB::GetRowWithQuery($sql, $params)  // Get single row
DB::GetRow($table, $keyvalue)       // Get row by primary key
DB::GetRow($table, $id, $keyname)   // Get row by specific key
DB::GetRowsMatch($table, $criteria) // Get rows matching criteria
DB::Insert($table, $data)           // Insert new row, returns ID
DB::Commit($table, $data)           // Insert or update (REPLACE)
DB::Update($table, $where, $data)   // Update existing rows
DB::RemoveRow($table, $keyvalue)    // Delete row by key

Logging

Log::debug($module, $text)   // log/debug.YYYY-mm.log
Log::text($module, $text)    // log/log.YYYY-mm.log  
Log::audit($module, $text)   // System journal

Profiler

Profiler::log($text, $indent_level)  // Runtime profiling
Profiler::$log                       // Access logged data

Coding Conventions

File Structure

• Views: views/{pagename}.php
• Components: components/{category}/{name}.php
• Classes: lib/{name}.class.php
• Utilities: lib/{name}.php

JS and PHP Coding Style

• Use <?= for output, use escaping functions safe(), asafe(), and jsafe() as appropriate
• snake_case for functions/methods
• PascalCase for classes
• kebab-case for file/directory names
• Always include <?php opening tag
• Use uquery.js (documentation: uquery.md) for DOM manipulation

Component Pattern

<?php return [
    'render' => function($prop) {
        return "<div class='{$prop['class']}'>{$prop['content']}</div>";
    },
    'render:variant' => function($prop) { /* alternative render */ },
    'about' => 'Component description'
];

URL Handling

• Use URL::Link() for all internal links
• Views auto-map to URLs (views/users.php → /users)

Built-in Libraries

• uquery.js - jQuery-like DOM manipulation
• morphdom.js - DOM diffing
• macrobars.js - JavaScript templating

Common Patterns

New Page

1. Create views/{pagename}.php
2. Set URL::$page_type to 'json' or 'blank' if page is AJAX
3. Content (auto-wrapped by theme page variant controlled by URL::$page_type)

New Component

1. Create components/{category}/{name}.php
2. Return array with render function
3. Use component('components/{category}/{name}', $props)

Error Handling

• Logging: Use Log::debug() for development, Log::audit() for security
• Profiling: Use Profiler::log() for performance analysis

Development Notes

• Server-side rendering preferred over SPA approach
• Component system encourages reusability
• Single entry point simplifies routing/middleware