A PHP + JSON site can be set up in a way that makes AI-assisted development smooth and fast, or in a way that makes it frustrating and error-prone. The difference is mostly in the structural decisions made early — decisions that are easy to get right if you know what to aim for.
One entry point, one router
Every request should flow through a single entry point — typically index.php — which hands off to a bootstrap file that handles routing, loads content, and resolves the template. There should be no competing routing systems, no alternative entry points for different content types, no special cases that bypass the main path.
This matters for AI tools because the routing path is one of the first things they need to understand. A single, traceable path from URL to rendered page means an AI assistant can follow the logic in one pass and make changes confidently. A fragmented routing system — multiple entry points, different logic for different content types — forces the AI to hold more complexity in context and increases the chance of a change breaking something it did not trace.
Consistent content schemas
Every content record of the same type should have the same shape. All articles should have the same fields. All categories should have the same fields. Fields that are sometimes present and sometimes not — or that sometimes contain strings and sometimes arrays — create ambiguity that AI tools handle poorly.
Define your schema explicitly. Write one canonical example of each content type. When an AI assistant is asked to create a new article or category, give it that canonical example as the pattern to match. The output will be consistently structured and will validate without manual correction.
Thin templates with named functions
Templates should render — they should not compute. Logic belongs in named functions in the bootstrap file, not inlined into template PHP. A template that calls site_resolve_sidebar_profile($view) is readable and modifiable. A template with thirty lines of inline logic is a maintenance problem and an AI liability.
Named functions are also self-documenting. An AI assistant reading a template that calls site_find_related_articles($article) understands what that call does without needing to trace through the implementation. An AI assistant reading inline logic has to parse it every time.
Validate everything, always
PHP lint and JSON validation should be part of every change cycle. Both are one-line commands. Running them after every file edit catches syntax errors immediately — before they surface as mysterious rendering failures.
AI tools can produce valid-looking PHP or JSON that contains subtle errors. A malformed JSON file fails silently in some configurations and loudly in others. Running json_decode with JSON_THROW_ON_ERROR catches the problem at the source.
The bootstrap as the single source of truth
All application functions, routing logic, content loading, and sidebar resolution should live in one file — the bootstrap. Not split across a lib directory, not distributed into per-feature files, not duplicated in templates. One file.
For a solo-operator site, this is not a compromise — it is an advantage. An AI assistant that needs to understand how the application works can read one file. The entire application logic is visible in a single pass. That transparency is worth more than the organisational neatness of a multi-file architecture that an AI has to reconstruct from pieces.