dockerank2/README.md

# Annunk

A multi-user web application for sending learning insights and training content. Powered by AI (OpenRouter.ai, OpenAI, StepFun, llama.cpp, QwenCloud) with Telegram bot integration, real-time updates, and comprehensive dashboards.

## Features

### User Features
- **Multi-user platform** with individual login, password, dashboard, and data
- **Subject Management**: Choose from system subjects or create your own
- **AI-Generated Insights**: Receive personalized learning insights via configurable AI provider
- **Multi-Provider AI**: Supports OpenRouter, OpenAI, StepFun, local llama.cpp, and QwenCloud
- **Detailed Scheduling**: Configure multiple times, weekdays, and timezone per subject
- **Insight Language**: Choose per-subject language (Portuguese, English, Spanish)
- **Delivery Channels**: Dashboard always enabled, Telegram optional per subject
- **Telegram Bot Integration**: Each user configures their own Telegram bot
- **Token Consumption Tracking**: Monitor input and output token usage with progress bar
- **Multilingual Interface**: Portuguese (Brazil), English, and Spanish
- **Dashboard**: Real-time chat-like interface with ApexCharts (token usage, insights per subject, weekly activity)
- **AI Chat**: Direct conversation with AI models via `/dashboard/chat` with content filtering
- **Profile Management**: Name, email, phone, language, timezone, password change
- **Password Change**: Users can change password without current password
- **Billing**: Subscribe to plans, view invoices, download PDFs

### SuperAdmin Features
- **Full System Control**: Complete system management dashboard
- **User Management**: Approve/reject, verify email, pause/activate, edit users, change passwords
- **Role Assignment**: Change user roles (admin/superadmin)
- **Token Limits**: Set per-user token consumption limits
- **Subscription Plans**: Create/edit plans with custom prices, durations, and token limits
- **Payment Approval**: Approve payments, generate PDF invoices
- **System Subjects**: Create and manage global learning subjects
- **System Statistics**: View total users, active users, pending approvals, revenue
- **AI Provider Configuration**: Configure AI provider via .env
- **User Password Management**: Edit user passwords directly without current password

### Admin Features
- **Subject Management**: Create, edit, deactivate custom subjects
- **Subject Deactivation**: Deactivating a subject automatically deletes all scheduled insights
- **AI-Generated Introductions**: Generate subject introductions automatically via AI
- **Insight Management**: View, generate, and delete insights
- **Schedule Management**: Configure delivery schedules per subject
- **Telegram Integration**: Connect and test Telegram bot
- **Billing**: Subscribe to plans, view invoices
- **Custom Subject Editing**: Edit name and active status of personal PDF subjects

### Technical Features
- **Math Captcha**: Simple addition-based CAPTCHA on all public forms (MIT-licensed)
- **CSRF Protection**: All forms protected against CSRF attacks
- **Responsive Design**: Fully responsive layout (mobile-first)
- **PDF Reports**: Generate and download invoices via Spatie Laravel PDF
- **Cookie Consent**: LGPD/GDPR compliant cookie consent management
- **Legal Pages**: Terms of use, privacy policy, and cookie policy
- **Notifications**: Dashboard notifications for payments, expirations, admin messages
- **Real-time Updates**: Laravel Reverb for live notifications

## Tech Stack

| Technology | Version | Purpose |
|-----------|---------|---------|
| Laravel | 13 | PHP Framework |
| PHP | 8.3 | Runtime |
| MariaDB | Latest | Database |
| Redis | Latest | Cache & Sessions |
| Tailwind CSS | 4 | CSS Framework |
| Blade | - | Templating Engine |
| Spatie Laravel Permission | 8 | Role-Based Access Control |
| Livewire Powergrid | 6 | Advanced Data Tables |
| Spatie Laravel PDF | 2 | PDF Generation |
| Laravel Mail | - | Email Notifications |
| Laravel Reverb | 1 | Real-time WebSocket Events |
| ApexCharts | Latest | Interactive Charts |
| OpenRouter.ai | - | AI API (default) |
| OpenAI API | - | AI API (optional) |
| StepFun API | - | AI API (optional) |
| QwenCloud API | - | AI API (optional) |
| llama.cpp | - | Local AI (optional) |
| Nutgram | Latest | Telegram Bot Framework |
| Alpine.js | 3 | JavaScript Interactions |

## System Architecture

```
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, ContentFilterRule
├── Models/                 # User, Subject, Insight, UserSubject, TelegramUser, TokenUsage, UserConsent, SubscriptionPlan, UserSubscription, Invoice, UserNotification
├── Services/               # AIService (multi-provider), TelegramService, MarkdownService
└── Providers/              # AppServiceProvider
```

## Requirements

- PHP 8.3+
- Composer 2.x
- Node.js 20+
- MariaDB 10+
- Redis
- Docker & Docker Compose (recommended)

## Installation

### Docker Installation (Recommended)

The project includes Docker configuration for easy deployment.

1. **Clone the repository:**
    ```bash
    git clone <repository-url> annunki
    cd annunki
    ```

2. **Configure environment:**
    ```bash
    cp .env.example .env
    php artisan key:generate
    ```

3. **Configure `.env` file:**
    ```env
    APP_NAME=Annunk
    APP_URL=http://localhost:16790
    DB_CONNECTION=mariadb
    DB_HOST=127.0.0.1
    DB_PORT=3306
    DB_DATABASE=annunki
    DB_USERNAME=root
    DB_PASSWORD=your_password

    # AI Provider (choose one)
    AI_DEFAULT_PROVIDER=openrouter
    OPENROUTER_API_KEY=sk-or-v1-...
    OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free

    # Optional AI Providers
    # OPENAI_API_KEY=sk-...
    # STEPFUN_API_KEY=...
    # QWEN_API_KEY=...
    # LLAMACPP_BASE_URL=http://localhost:8080/v1/
    ```

4. **Install dependencies:**
    ```bash
    composer install
    npm install
    npm run build
    ```

5. **Run migrations and seeders:**
    ```bash
    php artisan migrate --force
    php artisan db:seed --force
    php artisan db:seed --class=PlanSeeder --force
    ```

6. **Start the application:**
    ```bash
    php artisan serve --port=16790
    ```

### Docker Compose Setup

The project includes Docker Compose configuration:

```bash
docker compose up -d
```

**Default ports:**
- Application: `http://localhost:16790`
- MariaDB: `localhost:16791`
- Redis: `localhost:16792`

## Default Credentials

| Role | Email | Password |
|------|-------|----------|
| SuperAdmin | marcocosta@gmx.com | superadmin123456 |
| Test User | teste@annunki.com | teste123 |

## Default Subjects

1. Aprendizado e Treinamento de Inglês (English Language)
2. Aprendizado e Treinamento de Administração de Pequenos Negócios
3. Aprendizado e Treinamento de Estoicismo (Stoicism)
4. Aprendizado e Treinamento de Eletrônica (Electronics)
5. Aprendizado e Treinamento de As Leis do Triunfo
6. Aprendizado e Treinamento de Culinária Vegetariana

## Default Subscription Plans

| Plan | Price | Duration | Token Limit |
|------|-------|----------|-------------|
| Básico Mensal | R$ 29,90 | 30 days | 50k |
| Premium Mensal | R$ 59,90 | 30 days | 200k |
| Anual Premium | R$ 399,90 | 365 days | 500k |

## User Roles

### SuperAdmin
- Full system access
- User management (approve, verify email, pause, edit, delete, change password)
- System subject management
- AI provider configuration
- Billing management (plans, payments, invoices)
- System statistics

### Admin (Regular User)
- Subject subscription and management
- Personal subject creation
- Insight viewing and generation
- Telegram integration (own bot)
- Profile management
- Token usage monitoring
- Billing (subscribe, view invoices)
- Password change without current password

### Regular User
- Subject subscription
- Dashboard access
- Insight viewing
- Profile management
- Telegram integration

## User Flow

1. **Registration**: New user registers via public registration form (Math Captcha)
2. **Approval**: SuperAdmin approves the new user account
3. **Login**: After approval, user logs in (Math Captcha)
4. **Language Selection**: User selects preferred language and timezone
5. **Subject Selection**: User subscribes to system subjects or creates custom ones
6. **Scheduling**: User configures insight delivery schedule (multiple times, weekdays)
7. **Delivery Channels**: Choose Dashboard and/or Telegram
8. **Insight Generation**: AI generates insights based on selected subjects
9. **Delivery**: Insights appear on dashboard and optionally via Telegram
10. **Password Management**: Users can change password without current password

## AI Providers Configuration

```env
# Default provider
AI_DEFAULT_PROVIDER=openrouter

# OpenRouter
OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free

# OpenAI
# AI_DEFAULT_PROVIDER=openai
# OPENAI_API_KEY=sk-...
# OPENAI_MODEL=gpt-4o-mini

# StepFun
# AI_DEFAULT_PROVIDER=stepfun
# STEPFUN_API_KEY=...
# STEPFUN_MODEL=step-3.5-flash

# llama.cpp (local)
# AI_DEFAULT_PROVIDER=llamacpp
# LLAMACPP_BASE_URL=http://localhost:8080/v1/

# QwenCloud
# AI_DEFAULT_PROVIDER=qwen
# QWEN_API_KEY=...
# QWEN_MODEL=qwen-max
```

## Console Commands

```bash
# Send scheduled insights to users
php artisan insights:send

# Send insights for a specific user
php artisan insights:send --user=1

# Send insights for a specific subject
php artisan insights:send --subject=1
```

## Scheduler (Cron Job)

The insight scheduling system requires a cron job on the Linux host to function. The Laravel Scheduler needs only **1 crontab entry**.

### Cron Configuration

For Docker deployment, add this line to the host crontab:

```bash
* * * * * docker exec -u www-data dockerank2 php /var/www/html/artisan schedule:run >> /var/log/annunk-cron.log 2>&1
```

### Scheduled Tasks

| Command | Frequency | Description |
|---------|-----------|-------------|
| `insights:send` | Every 15 minutes | Sends scheduled insights to users |
| `insights:send` | Daily 00:00 | Additional verification |

### How it works:
1. Cron executes `php artisan schedule:run` every minute
2. Laravel Scheduler checks for pending tasks
3. `insights:send` command processes schedules using each user's timezone
4. Generates insights via AI and sends to Dashboard and/or Telegram as configured
5. Logs in `storage/logs/insights-scheduler.log`

## Multilingual Support

Three languages supported:
- **pt_BR**: Português do Brasil (default)
- **en**: English
- **es**: Español

Users switch languages via the navbar dropdown (Alpine.js). Translation files in `lang/{locale}/`.

## Security

- **Math Captcha**: All public forms (login, register) require solving a math addition
- **CSRF Protection**: All forms include CSRF tokens
- **User Approval**: New registrations require SuperAdmin approval
- **Role-Based Access**: Spatie Laravel Permission controls access to routes
- **Input Validation**: All user input is validated and sanitized
- **Content Filtering**: Chat messages are validated against prohibited content (profanity, pornography, politics, religion, prejudice)
- **AI Model Hidden**: Admin users cannot see which AI model is being used
- **Password Security**: Passwords are hashed using bcrypt

## API Routes

### Admin (`/admin/*`)
- `subjects` - CRUD + subscribe, toggle, schedule, unsubscribe, send-insight, send-introduction
- `insights` - List, generate, create, delete
- `telegram` - Connect, test, disconnect
- `billing` - Subscribe, invoices, notifications
- `custom-subjects` - CRUD + ask questions for PDF subjects

### SuperAdmin (`/superadmin/*`)
- `users` - CRUD + approve, reject, toggle-active, verify-email, change-password
- `system` - System subjects management
- `billing` - Plans CRUD, approve payments, cancel subscriptions, invoices

### Legal (`/legal/*`)
- `terms`, `privacy`, `cookies`, `accept`, `history`, `cookie-banner/accept`

## Recent Updates

### Chat Content Filter
- Content filter rule blocks messages with profanity, pornography, politics, religion, and prejudice
- Warning banner displayed on chat page advising users on prohibited content
- Validation applied to all chat messages before sending to AI

### Custom Subject Editing
- Users can now edit the name and active status of their personal PDF subjects
- Edit form accessible from the custom subjects list
- Inactive subjects do not receive scheduled insights

### Password Management
- Users can change password without entering current password
- SuperAdmin can edit user passwords directly
- Eye icon toggle for password visibility in all password fields

### Subject Management
- Deactivating a subject automatically deletes all scheduled insights
- Subject introduction is now AI-generated and auto-saved
- Introduction button generates content automatically without manual editing

## Environment Variables

Key environment variables for configuration:

```env
APP_NAME=Annunk
APP_URL=http://localhost:16790
APP_LOCALE=pt_BR

# Database
DB_CONNECTION=mariadb
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=annunki
DB_USERNAME=root
DB_PASSWORD=

# AI Configuration
AI_DEFAULT_PROVIDER=openrouter
OPENROUTER_API_KEY=
OPENROUTER_MODEL=google/gemini-2.0-flash-exp:free

# Mail Configuration
MAIL_MAILER=smtp
MAIL_HOST=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
MAIL_ENCRYPTION=tls

# Telegram (optional)
TELEGRAM_BOT_TOKEN=
TELEGRAM_CHAT_ID=
```

## License

**Proprietary** - All Rights Reserved

This software is proprietary and owned by **Syspanel** (syspanel.com.br).

All third-party libraries, extensions, and icons used in this system are MIT-licensed.

The Math Captcha implementation is custom-built and MIT-licensed (no external CAPTCHA libraries).

## Support

For support, contact: Syspanel - www.syspanel.com.br