# 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)