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