dockerank2/RULES.md

Annunk Development Rules

Project Overview

Annunk is a multi-user web application for sending learning insights and training content via AI (OpenRouter.ai, OpenAI, StepFun, llama.cpp, QwenCloud), Telegram bot, and dashboard. Built with Laravel 13 + PHP 8.3 + MariaDB.

Code Standards

• All PHP code must follow PSR-12 coding standards
• All PHP source files must include technical comments in English using the PHPDoc standard (@param, @return, @throws, @property, etc.)
• Use meaningful variable and function names (self-documenting code)
• Keep methods small and focused (max 50 lines per method)
• Use dependency injection instead of facades when possible
• Use type hints for all function parameters and return types
• Declare strict types (declare(strict_types=1)) in all PHP files

Architecture

Directory Structure

app/
├── Console/Commands/       # Artisan commands (SendScheduledInsights)
├── Http/
│   ├── Controllers/
│   │   ├── Admin/          # Admin user controllers (Subject, Insight, Telegram, Billing)
│   │   ├── Auth/           # Authentication controllers (login/register with MathCaptcha)
│   │   └── SuperAdmin/     # SuperAdmin controllers (User, System, Billing)
│   ├── Middleware/         # SetLocale, EnsureUserConsent
│   └── Validation/         # MathCaptchaRule
├── Models/                 # User, Subject, Insight, UserSubject, TelegramUser, TokenUsage, UserConsent, SubscriptionPlan, UserSubscription, Invoice, UserNotification
├── Services/               # AIService (multi-provider), TelegramService, MarkdownService
└── Providers/              # AppServiceProvider

Naming Conventions

• Controllers: SingularPascalCaseController
• Models: SingularPascalCase
• Migrations: YYYY_MM_DD_HHMMSS_descriptive_name
• Services: DescriptivePascalCaseService
• Middleware: DescriptivePascalCase
• Validation Rules: DescriptivePascalCaseRule
• Routes: kebab-case for URLs
• Blade Views: kebab-case for directories and files

Database

• All migrations must be reversible
• Use foreign key constraints with cascadeOnDelete()
• Index frequently queried columns
• Use transactions for multi-step operations
• All tables must have created_at and updated_at timestamps

Security

• All user input must be validated and sanitized
• CSRF protection on all forms
• Math Captcha on all public forms (login, register)
• New users must be approved by SuperAdmin
• Use role-based access (Spatie Laravel Permission)
• Admin users cannot see the AI model name

Roles & Permissions

Roles

• SuperAdmin: Full system control, user management, system subjects, billing, plans
• Admin: Regular user with access to subjects, insights, Telegram, billing

Route Protection

• role:admin|superadmin - Admin routes
• role:superadmin - SuperAdmin routes

Multilingual

• Supported locales: pt_BR (Português Brasil), en (English), es (Español)
• All UI text must use Laravel's __() helper or @lang() directive
• Translation files in lang/{locale}/ directory
• User can switch language via Alpine.js dropdown in navbar
• Selected locale stored in session and user profile

Frontend

• Tailwind CSS (v4) for all styling
• Blade templates with @extends and @section/@yield
• Fully responsive (mobile-first)
• Alpine.js for interactive components (dropdowns, modals)
• ApexCharts for charts and statistics
• Math Captcha on all public forms (MIT-licensed, no external libraries)
• All icons via inline SVG (MIT-licensed)

AI Integration (Multi-Provider)

Supported Providers

Provider	Base URL	Config Key
OpenRouter.ai	https://openrouter.ai/api/v1/	OPENROUTER_API_KEY
OpenAI	https://api.openai.com/v1/	OPENAI_API_KEY
StepFun	https://api.stepfun.ai/step_plan/v1/	STEPFUN_API_KEY
llama.cpp (Local)	http://localhost:8080/v1/	LLAMACPP_BASE_URL
QwenCloud	https://api.qwencloud.com/v1/	QWEN_API_KEY

Rules

• All AI-generated content must be logged with token usage
• Track input_tokens and output_tokens for each request
• Store AI responses in the insights table
• Implement rate limiting to control costs
• Configurable provider via AI_DEFAULT_PROVIDER env variable
• Include subject context and language preference in all prompts
• Implement fallback for AI service failures
• Log all AI API errors for debugging

Content Guidelines

• AI-generated insights must be relevant to the selected subject
• Include subject context in all AI prompts
• Set appropriate temperature and max_tokens parameters
• Implement fallback for AI service failures
• Log all AI API errors for debugging

Cost Management

• Monitor token consumption per user
• Set daily/monthly token limits if needed
• Alert on unusual token usage patterns
• Cache common AI responses when appropriate
• Use free models when possible to reduce costs

Privacy

• Do not send sensitive user data to AI APIs
• Anonymize user information in prompts
• Review AI outputs before sending to users
• Implement content filtering if needed

Prompt Engineering

• Use clear and specific prompts
• Include context about the subject and user preferences
• Set appropriate response formats
• Test prompts regularly for quality
• Document prompt templates

Telegram Integration

• Each user configures their own Telegram bot (bot_token, chat_id)
• Users can enable/disable Telegram delivery per subject via delivery_channels
• Test button to verify bot connection
• Insights sent to Telegram when telegram channel is enabled

Billing & Subscriptions

• SuperAdmin creates/manages subscription plans (name, price, duration, token limit)
• Users subscribe to plans (creates pending invoice)
• SuperAdmin approves payments (generates PDF invoice, notifies user)
• Users can view invoices and download PDFs
• Dashboard notifications for payment status, expiring subscriptions

Testing

• Write tests for all new features using PHPUnit
• Maintain minimum 80% code coverage
• Test edge cases and error conditions
• Use descriptive test method names

Git

• Write clear commit messages in English
• Keep commits atomic and focused
• Never commit secrets, credentials, or .env files

License

• Annunk is Proprietary - owned by Syspanel (syspanel.com.br)
• All libraries, extensions, and icons used must be MIT-licensed
• Math Captcha implementation is MIT-licensed (no external libraries)

Environment

• System URL: http://localhost:16790
• SuperAdmin: marcocosta@gmx.com / superadmin123456
• Test user: teste@annunki.com / teste123
• System location: /home/marco/Dockers/dockerank2/app

Tech Stack

Technology	Version	Purpose
Laravel	13	PHP Framework
PHP	8.3	Runtime
MariaDB	Latest	Database
Tailwind CSS	4	CSS Framework
Blade	-	Templating Engine
Spatie Laravel Permission	8	RBAC
Spatie Laravel PDF	2	PDF Generation
Laravel Mail	-	Email Notifications
Laravel Reverb	1	Real-time Events
ApexCharts	Latest	Charts
OpenRouter.ai	-	AI API (default)
OpenAI API	-	AI API (optional)
Nutgram	Latest	Telegram Bot
Alpine.js	3	JavaScript Framework