dockergprompt/RULES.md

AI Implementation Rules - GPrompt

Project Context

This is a Laravel 13 prompt generation system running in Docker container dockergprompt, project path /home/marco/Dockers/dockergprompt/app, accessible at localhost:16820.

Tech Stack

• Laravel 13 with Blade templates
• PHP 8.3
• MariaDB database
• Bootstrap 5
• SbAdmin 2 dashboard theme (MIT license)
• Laravel Breeze for authentication
• Laravel Boost for AI assistance

Database Credentials

• Host: mysql
• Database: dockergprompt
• Username: admin
• Password: admin123

AI Provider Configuration

Environment variables in .env:

• OPENROUTER_API_KEY - OpenRouter API key
• OPENROUTER_BASE_URL - https://openrouter.ai/api/v1
• STEPFUN_API_KEY - StepFun API key
• STEPFUN_BASE_URL - https://api.stepfun.ai/v1
• LLAMACPP_BASE_URL - Local llama.cpp server URL (default: http://localhost:8080)

AI Models Available

OpenRouter:

• inclusionai/ling-3.0-flash:free
• openrouter/free
• deepseek/deepseek-v4-flash

StepFun:

• step-3.5-flash
• step-3.7-flash

Llama.cpp (Local):

• Qwen3-8B-Q4_K_M.gguf
• Llama-3.2-3B-Instruct-uncensored-Q4_K_M.gguf
• ibm-granite_granite-4.1-3b-Q4_K_M.gguf
• qwen2.5-coder-3b-instruct-q4_k_m.gguf
• LiquidAI_LFM2.5-1.2B-Instruct-Q4_0.gguf

User Roles

• SuperAdmin: Full system control + usage
• User: System usage only, requires SuperAdmin approval

File Structure Rules

• Controllers: app/Http/Controllers/{Module}/{Entity}Controller.php
• Models: app/Models/{Entity}.php
• Requests: app/Http/Requests/{Module}/{Entity}Request.php
• Services: app/Services/{Module}/{Entity}Service.php
• Policies: app/Policies/{Entity}Policy.php
• Migrations: database/migrations/YYYY_MM_DD_HHMMSS_create_{table}_table.php
• Views: resources/views/{module}/{action}.blade.php

Code Standards

• PSR-12 compliance
• PHPDoc comments in English for all methods
• SOLID principles
• Type hints for all method parameters and return types
• Strict typing enabled (declare(strict_types=1);)
• No var keyword, use private/protected/public
• No deprecated functions
• No dd(), dump(), ray() in production code

Security Rules

• CSRF: All forms must have @csrf directive
• XSS: Use Blade's automatic escaping, never {!! !!} unless absolutely necessary
• SQL Injection: Use Eloquent ORM or Query Builder with bindings
• Mass Assignment: Use $fillable or $guarded explicitly in models
• Authorization: Use Policies or Gates for all actions
• Password Security: Hash passwords with Bcrypt, use password:confirm validation rule
• Captcha: Native Laravel captcha with arithmetic operations for public forms
• Rate Limiting: Apply appropriate rate limits on forms and API endpoints

Frontend Rules

• Bootstrap 5 with BI icons (MIT license only)
• SbAdmin 2 theme with responsive sidebar (< > toggle)
• Mobile: sidebar only visible on hamburger menu click
• Portuguese (Brazil) for all views
• Breadcrumbs on every page
• Password visibility toggle (eye icon) on all password fields
• Modern, responsive design

Prompt Engineering Form Fields

The prompt creation form must include:

1. Objective - What the prompt should achieve
2. Context - Background information
3. Persona/Role - Who the AI should be
4. Tone/Style - Communication style
5. Constraints - Limitations and rules
6. Output Format - Expected response structure
7. Examples - Few-shot examples
8. Variables - Dynamic placeholders
9. Temperature (0.0-1.0)
10. Max Tokens
11. Provider selection (dropdown)
12. Model selection (dynamic dropdown based on provider)

Testing Requirements

• All tests in tests/ directory
• Feature tests for all CRUD operations
• Browser tests with Playwright for UI validation
• Test credentials:
  • SuperAdmin: superadmin@sistema.com / superadmin123
  • User: user@sistema.com / user123

Prohibited Practices

• No @section stacking in Blade
• No inline CSS or JS (use app.css/app.js)
• No hardcoded URLs or paths
• No magic numbers (define constants)
• No commented-out code
• No TODO, FIXME, XXX comments
• No external scripts except CDN Bootstrap/BI

Performance Rules

• Eager load relationships to prevent N+1
• Use database indexing on foreign keys
• Cache expensive queries
• Paginate large datasets
• Compress images and assets

Documentation Rules

• All documentation in Portuguese (Brazil)
• README.md with installation and usage instructions
• RULES.md (this file) in English
• LICENCE file
• Technical documentation in .md format

Command Execution

Before writing code:

1. Check existing routes with php artisan route:list
2. Check database schema with migrations
3. Review logs with Laravel Boost if errors occur
4. Run tests after implementation: php artisan test
5. Run Playwright tests: npm run test:e2e

Deliverable Standards

• 100% production-ready code
• No incomplete implementations
• No mocks or stubs
• Complete error handling
• All validation rules defined
• All policies implemented
• Complete translations (pt-BR)