Mind-Vision-Code/.ai/skills/mvc/SKILL.md

MVC Framework Skill

Purpose

Use this skill for MindVisionCode PHP framework architecture, routing, dispatching, controllers, actions, ViewModels, templates, and HTTP request/response flow.

---

Project Identity

This project is a small PHP MVC framework called MindVisionCode PHP.

It is intentionally inspired by a Classic ASP MVC framework style:

• Central dispatcher
• Controllers and actions
• ViewModels
• Repository classes
• Simple validation
• Database migrations
• Small, readable files
• Minimal dependencies

Do not turn this into Laravel, Symfony, Slim, CakePHP, or another large framework.

---

Request Flow

Browser
  → public/index.php
  → Request
  → Dispatcher
  → Router
  → Route
  → Controller
  → ViewModel/Repository/Service
  → View
  → Response

---

Project Structure

Preferred structure:

project-root/
  public/
    index.php
  src/
    Controller/
    Service/
    Repository/
    Entity/
    ValueObject/
    ViewModel/
    Http/
    Routing/
    Validation/
    Database/
    Migration/
  templates/
  config/
  tests/
  var/
    cache/
    logs/
  vendor/
  composer.json

Rules:

• public/ is the web root.
• Do not expose src/, config/, tests/, vendor/, .ai/, or .env files through the web server.
• Put application code under src/.
• Put generated cache/log files under var/ or another ignored runtime directory.
• Keep secrets outside the web root.

---

Development Commands

Install dependencies:

composer install

Regenerate autoload files:

composer dump-autoload

Run local server:

php -S localhost:8000 -t public

Run basic tests:

php tests/run.php

---

Framework Coding Rules

• Keep code simple and readable.
• Prefer small classes.
• Use typed properties and return types where practical.
• Avoid hidden magic.
• Do not add dependencies without a clear reason.
• Preserve the framework style.
• Explain any architectural changes.

---

Controller Rules

• Keep controllers thin.
• Validate request method and request shape at the boundary.
• Do not put database query details directly in controllers when a repository or service is more appropriate.
• Do not put template rendering logic inside business services.
• Return or produce a response through the framework’s response mechanism.

---

ViewModel Rules

• Use ViewModels to shape data for views.
• Keep ViewModels simple and explicit.
• Avoid passing raw database rows directly into complex templates when a ViewModel would make the template clearer.
• Do not put database access inside ViewModels unless the existing project convention explicitly does that.

---

Templates and Views

Keep presentation separate from business logic.

Rules:

• Do not query the database from templates.
• Do not place business rules in templates.
• Escape output by default.
• Prefer simple view models or arrays passed into templates.
• Use a template engine with automatic escaping only if it fits the project and does not make the framework unnecessarily large.

Plain PHP template example:

<h1><?= e($pageTitle) ?></h1>

<ul>
    <?php foreach ($users as $user): ?>
        <li><?= e($user->name()) ?></li>
    <?php endforeach; ?>
</ul>

---

HTTP and Web Application Rules

Rules:

• Use the front controller pattern where appropriate.
• Keep routing separate from business logic.
• Validate request methods.
• Use CSRF protection for state-changing forms.
• Use proper HTTP status codes.
• Redirect after successful POST to avoid duplicate form submission.
• Do not trust headers such as X-Forwarded-For unless configured behind a trusted proxy.

Example POST guard:

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Method Not Allowed');
}

---

Architecture Guardrail

When adding features, preserve the small-framework character:

• Prefer explicit code over hidden convention.
• Prefer simple routing over complex annotation systems.
• Prefer plain PHP views unless a project decision says otherwise.
• Prefer focused services and repositories over large framework abstractions.
• Do not introduce a large package just to solve a small problem.