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:

   git clone <repository-url> annunki
   cd annunki
   

2. Configure environment:

   cp .env.example .env
   php artisan key:generate
   

3. Configure .env file:

   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:

   composer install
   npm install
   npm run build
   

5. Run migrations and seeders:

   php artisan migrate --force
   php artisan db:seed --force
   php artisan db:seed --class=PlanSeeder --force
   

6. Start the application:

   php artisan serve --port=16790
   

Docker Compose Setup

The project includes Docker Compose configuration:

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

# 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

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

* * * * * 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:

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