growup-crm/GEMINI.md

# Growup Pro - Krayin CRM Whitelabel Multi-tenant

## Project Overview

**Growup Pro** is a whitelabel implementation of [Krayin Laravel CRM](https://github.com/krayin/laravel-crm) with multi-tenancy support. The platform allows multiple companies/organizations to use the same CRM instance with complete data isolation through subdomain-based tenancy.

**CURRENT STATUS: FEATURE IMPLEMENTATION PHASE**
- **Multi-tenancy implementation**: Stable.
- **Authentication**: Stable (Infinite redirect loop resolved).
- **Core Systems**: Localhost and central domain detection working.
- **Goal**: Implement advanced admin features, Sentry integration, and finalize branding.

### Key Differentiators from Krayin
- **Rebranding**: Complete visual overhaul with Growup Pro branding
- **Multi-tenancy**: Isolated environments per client organization
- **Localization**: Full Portuguese (pt-BR) translation
- **White-label ready**: Easy customization per tenant

## Tech Stack

- **Framework**: Laravel (check composer.json for exact version)
- **Base CRM**: Krayin Laravel CRM
- **Database**: MySQL/PostgreSQL
- **Multi-tenancy Package**: [Tenancy for Laravel](https://tenancyforlaravel.com/docs/v3/introduction) (v3)
- **Frontend**: Blade templates with Alpine.js (Krayin default)
- **PHP Version**: 8.1+
- **Containerization**: Docker with Docker Compose
- **Orchestration**: Docker Swarm
- **Management**: Portainer
- **CI/CD**: Gitea Actions (GitHub Actions compatible)
- **Error Tracking**: Sentry for Laravel
- **Code Quality**: PHPStan (static analysis) + Laravel Pint (code formatter)
- **CDN**: Cloudflare (caching and DDoS protection) - **PRODUCTION ONLY**

## Project Structure

```
.
├── .gitea/
│   └── workflows/       # Gitea Actions CI/CD pipelines
│       ├── deploy.yml           # Production deployment
│       ├── deploy-staging.yml   # Staging environment deployment
│       └── tests.yml            # Automated testing pipeline
├── .husky/              # Git hooks (pre-commit, pre-push)
├── Makefile             # Common development commands
├── app/
│   ├── Models/          # Eloquent models (tenant-scoped)
│   ├── Http/
│   │   ├── Controllers/ # Application controllers
│   │   └── Middleware/  # Custom middleware (tenant identification)
│   └── Providers/       # Service providers
├── config/
│   └── tenancy.php      # Tenancy for Laravel configuration
├── database/
│   ├── migrations/      # Database migrations
│   │   ├── tenant/      # Tenant-specific migrations
│   │   └── landlord/    # Central database migrations
│   └── seeders/         # Seeders for tenants and central data
│       ├── DemoTenantSeeder.php    # Creates demo tenants for testing
│       └── ProductionSeeder.php    # Production data seeding
├── docker/
│   ├── Dockerfile       # Application container definition
│   ├── docker-compose.yml # Local development orchestration
│   └── docker-compose.prod.yml # Production stack definition
├── packages/            # Krayin core packages
│   └── Webkul/
│       └── ...
├── public/
│   └── assets/          # Growup Pro assets (logos, images)
├── resources/
│   ├── lang/
│   │   └── pt_BR/       # Portuguese translations
│   └── views/           # Blade templates (Growup Pro customized)
└── routes/
    ├── web.php          # Central app routes
    ├── tenant.php       # Tenant-specific routes
    ├── admin.php        # Admin dashboard routes (tenant management)
    └── api.php          # API routes
```

## Multi-tenancy Configuration

### Package: Tenancy for Laravel
We use **Tenancy for Laravel v3** for robust multi-tenant architecture with automatic database switching and tenant identification.

### Tenant Identification Strategy
- **Method**: Subdomain-based identification
- **Domain**: `growuppro.com.br`
- **Pattern**: `{tenant}.growuppro.com.br`
- **Examples**: 
  - `empresa1.growuppro.com.br` → Tenant: empresa1
  - `empresa2.growuppro.com.br` → Tenant: empresa2
  - `demo.growuppro.com.br` → Tenant: demo

### Data Isolation
- **Approach**: Separate database per tenant (recommended by Tenancy for Laravel)
- Database naming: `tenant_{tenant_id}` (e.g., `tenant_empresa1`)
- Central database: `growuppro_central` (stores tenant metadata, domains, users)
- Automatic tenant context switching via middleware
- Models automatically scoped to current tenant

### Tenant Features
Each tenant has isolated:
- **Data**: Leads, contacts, deals, products, activities
- **Users**: Separate user base with roles/permissions
- **Settings**: Email configuration, notifications, workflows
- **Customization**: Optional CSS overrides, email templates

## Branding & Localization

### Growup Pro Visual Identity
- **Application Name**: Growup Pro (replacing all Krayin mentions)
- **Logo**: Custom Growup Pro logo in all interfaces
- **Color Scheme**: [Define primary/secondary colors when ready]
- **Typography**: [Define font family when ready]
- **UI/UX**: Modern, clean interface aligned with Growup Pro brand

### Translation (pt-BR)
- All user-facing text translated to Portuguese (Brazil)
- Language files in `resources/lang/pt_BR/`
- Default locale: `pt_BR` (set in `config/app.php`)
- Maintain translation keys for easy updates
- Include tenant-customizable text snippets

### Customization Locations
1. **Logo**: `public/assets/images/logo.png` (central) and tenant-specific storage
2. **Translations**: `resources/lang/pt_BR/`
3. **Views**: `resources/views/` (customized Krayin templates)
4. **Styles**: `public/assets/css/custom.css` (Growup Pro overrides)
5. **Config**: `config/growuppro.php` (application-specific settings)

## Docker & Deployment Architecture

### Container Strategy
The application runs in Docker containers orchestrated by Docker Swarm and managed through Portainer.

### Docker Compose Structure
- **Development**: `docker-compose.yml` (local development with hot-reload)
- **Production**: `docker-compose.prod.yml` (optimized for Swarm deployment)

### Services
Typical stack includes:
- **app**: PHP-FPM application container (Growup Pro)
- **nginx-proxy-manager**: Nginx Proxy Manager for reverse proxy, SSL, and domain management (managed via Portainer)
- **database**: MySQL/PostgreSQL (central + tenants)
- **redis**: Session and cache storage
- **queue**: Laravel queue worker for background jobs
- **scheduler**: Laravel scheduler (cron jobs)

### Image Management
- **Registry**: GitHub Container Registry (GHCR)
- **Image naming**: `ghcr.io/cauefaleiros/growup-pro:latest`
- **Tagging strategy**: Git commit SHA and semantic versioning
- **Tags**: `latest` (production), `dev` (development), `v{version}` (releases)

## CI/CD Pipeline with Gitea Actions

### About Gitea Actions
Gitea Actions (available since Gitea 1.19) is a built-in CI/CD solution similar and mostly compatible with GitHub Actions. It uses the same YAML workflow format and is compatible with most GitHub Actions marketplace plugins.

**Key Components:**
- **Gitea Server**: Hosts repositories and triggers workflows
- **act_runner**: Standalone runner program (written in Go) that executes jobs, based on a fork of nektos/act
- **Workflows**: YAML files stored in `.gitea/workflows/` directory (compatible with GitHub Actions syntax)

**Compatibility:**
- Same YAML syntax as GitHub Actions
- Can use most actions from GitHub marketplace (e.g., `actions/checkout@v4`, `actions/setup-node@v4`)
- Workflows are portable between GitHub and Gitea with minimal changes

### Deployment Flow
```
Developer pushes code to GitHub
         ↓
GitHub Actions workflow triggered
         ↓
1. Run tests (PHPUnit, Pest)
2. Build Docker image
3. Tag image with commit SHA
         ↓
Push image to GitHub Container Registry (GHCR)
         ↓
Call Portainer API (webhook or direct API)
         ↓
Portainer updates Docker Stack definition
         ↓
Docker Swarm pulls new image
         ↓
Swarm performs rolling update (zero-downtime)
         ↓
Health checks verify deployment
         ↓
Old containers removed
```

### GitHub Actions Workflow
Location: `.github/workflows/deploy.yml`

Key steps:
1. **Checkout code**
2. **Setup PHP & dependencies** (Composer install)
3. **Run code quality checks** (PHPStan, Pint)
4. **Run tests** (PHPUnit/Pest - ensure code quality)
5. **Build Docker image** with build args
6. **Login to GHCR** using GitHub token
7. **Push image** with appropriate tags
8. **Trigger Portainer** via API to update stack
9. **Verify deployment** (health check endpoint)
10. **Notify team** (Slack/Discord webhook on success/failure)

### Environment Variables
Managed through:
- **GitHub Secrets**: Sensitive data (API keys, tokens, Sentry DSN)
- **Portainer**: Stack environment variables
- **Docker Swarm Secrets**: Database credentials, API keys

### Portainer Integration
- **Portainer URL**: `https://148.230.76.122:9443`
- **API Endpoint**: `https://148.230.76.122:9443/api`
- **Authentication**: API token (stored in GitHub Secrets)
- **Stack Management**: Update existing stack with new image tag
- **Webhooks**: Optional webhook for automated redeploy
- **Nginx Proxy Manager**: Managed through Portainer for SSL certificates and domain routing

## Coding Conventions

### Models
All tenant-scoped models automatically inherit tenant context through Tenancy for Laravel:

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Lead extends Model
{
    // Tenancy for Laravel handles scoping automatically
    // No manual trait needed for tenant models
    
    protected $fillable = ['title', 'value', 'status'];
}
```

### Central Models
Models that exist in the central database (tenant metadata, etc.):

```php
<?php

namespace App\Models;

use Stancl\Tenancy\Database\Models\Tenant as BaseTenant;

class Tenant extends BaseTenant
{
    // Custom tenant attributes
    protected $fillable = [
        'id', 'company_name', 'subdomain', 'logo_url', 'primary_color'
    ];
}
```

### Controllers
- Follow Krayin's controller structure
- Tenant context is automatic (no manual checking needed)
- Use dependency injection and repository pattern
- Keep business logic in Service classes

### Migrations
Tenancy for Laravel separates migrations:

```php
// database/migrations/tenant/2024_xx_xx_create_leads_table.php
Schema::create('leads', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->decimal('value', 10, 2);
    // No tenant_id needed - separate databases per tenant
    $table->timestamps();
});

// database/migrations/2024_xx_xx_create_tenants_table.php (central)
Schema::create('tenants', function (Blueprint $table) {
    $table->string('id')->primary();
    $table->string('company_name');
    $table->string('subdomain')->unique();
    $table->timestamps();
});
```

### Routes
```php
// routes/tenant.php - Runs in tenant context
Route::middleware(['tenant'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
    Route::resource('leads', LeadController::class);
});

// routes/web.php - Central app (tenant selection, etc.)
Route::get('/', [HomeController::class, 'index']);
Route::post('/register-tenant', [TenantController::class, 'register']);
```

## Important Files to Know

### Configuration
- `config/app.php` - Application configuration (locale: pt_BR)
- `config/tenancy.php` - Tenancy for Laravel settings
- `config/growuppro.php` - Custom Growup Pro configuration
- `app/Http/Kernel.php` - Middleware registration

### Krayin Core
- `packages/Webkul/` - Krayin core packages (**never modify directly**)
- Extend functionality through Laravel's standard practices (service providers, custom packages)

### Docker & Deployment
- `docker/Dockerfile` - Application container definition
- `docker-compose.yml` - Local development environment
- `docker-compose.prod.yml` - Production stack for Swarm
- `.github/workflows/deploy.yml` - CI/CD pipeline

### Branding
- `public/assets/images/logo.png` - Growup Pro logo
- `resources/lang/pt_BR/` - Portuguese translations
- `resources/views/layouts/app.blade.php` - Main layout (branded)

## Resolved Issues (History)

### Authentication Stabilization
Previous critical issues with infinite redirect loops, CSRF token mismatches (419), and session persistence have been resolved. The authentication system is now stable across local, staging, and production environments.

### Multi-tenancy Setup
- **Localhost Detection**: Fixed `TenantCouldNotBeIdentifiedOnDomainException`.
- **Asset Loading**: Fixed 404 errors for tenant static assets.
- **Database Isolation**: Successfully implemented per-tenant databases.

---

## Development Workflow

### Development Environments
The project uses multiple environments for safe deployment:

1. **Local Development** (`localhost`)
   - Docker Compose for local stack
   - Hot reload enabled
   - Debug mode on

2. **Staging Environment** (`staging.growuppro.com.br`)
   - Production-like environment
   - Deployed from `staging` branch
   - Used for testing before production
   - Same infrastructure as production

3. **Production Environment** (`growuppro.com.br`)
   - Live environment
   - Deployed from `main` branch
   - Zero-downtime deployments

### Local Development
1. Clone repository
2. Copy `.env.example` to `.env` and configure
3. Run `docker-compose up -d`
4. Access: `http://localhost` or configured local domain
5. Create test tenants: `php artisan tenants:create`

### Making Changes
1. **Never modify Krayin core** - extend via Laravel patterns
2. **Test with multiple tenants** - always verify isolation
3. **Follow PSR-12** coding standards (enforced by Pint)
4. **Run quality checks** before committing:
   ```bash
   make lint        # Run PHPStan + Pint
   make test        # Run test suite
   ```
5. **Write tests** for new features (PHPUnit/Pest)
6. **Update translations** when adding UI text
7. **Document breaking changes** in pull requests
8. **Use pre-commit hooks** to catch issues early

### Testing Strategy
- **Unit Tests**: Core business logic, services
- **Feature Tests**: Tenant isolation, API endpoints
- **Browser Tests**: Multi-tenant user flows (Dusk)
- **Database Tests**: Migration rollback/forward
- Test with at least 2-3 active tenants
- **CI/CD Integration**: All tests run automatically on push
- **Coverage Goal**: Minimum 70% code coverage

### Deployment Process
1. **Create feature branch** from `main`
2. **Develop and test locally**
3. **Push to `staging` branch** for staging deployment
4. **Test on staging environment** (`staging.growuppro.com.br`)
5. **Create Pull Request** to `main` (after PR approval)
6. **Merge to `main`** - GitHub Actions runs automatically
7. **Monitor deployment** in Portainer
8. **Verify health checks** pass
9. **Test critical flows** on production
10. **Sentry** monitors for runtime errors

## Common Tasks

### Quick Development Commands (Makefile)
```bash
make dev              # Start local development environment
make prod             # Start production-like local environment
make test             # Run test suite
make lint             # Run PHPStan + Pint checks
make fix              # Auto-fix code style issues
make deploy-staging   # Deploy to staging
make deploy-prod      # Deploy to production
make logs             # Show application logs
make shell            # Enter application container shell
make db-fresh         # Fresh database with seeders
make tenant-create    # Create a new demo tenant
```

### Creating a tenant-scoped feature
1. Create migration in `database/migrations/tenant/`
2. Run migrations: `php artisan tenants:migrate`
3. Create model (no special traits needed)
4. Add routes in `routes/tenant.php`
5. Build controller with tenant-aware logic

### Adding a new translation
1. Edit `resources/lang/pt_BR/{file}.php`
2. Add translation key and Portuguese text
3. Use in Blade: `{{ __('messages.welcome') }}`
4. Test across different tenant contexts

### Customizing tenant branding
1. Store settings in Tenant model (JSON or relations)
2. Load in middleware or service provider
3. Pass to views via view composer
4. Cache for performance: `tenant()->cache('branding')`

### Updating Docker image
1. Modify `docker/Dockerfile` as needed
2. Test locally: `make build` or `docker-compose build app`
3. Push changes to GitHub
4. CI/CD handles the rest automatically

### Creating demo tenants for testing
```bash
# Using artisan command
php artisan tenants:seed

# Or via Makefile
make tenant-create

# Specify tenant details
php artisan tenants:create \
  --domain=demo.growuppro.com.br \
  --name="Empresa Demo" \
  --email=admin@demo.com
```

### Managing code quality
```bash
# Run static analysis
./vendor/bin/phpstan analyse

# Check code style
./vendor/bin/pint --test

# Auto-fix code style
./vendor/bin/pint

# Or use Makefile shortcuts
make lint  # Check only
make fix   # Auto-fix
```

### Setting up pre-commit hooks
```bash
# Install Husky (or similar)
npm install --save-dev husky

# Initialize hooks
npx husky init

# Add pre-commit hook
echo "make lint && make test" > .husky/pre-commit
chmod +x .husky/pre-commit
```

## Environment Variables

### Required Variables
```env
# Application
APP_NAME="Growup Pro"
APP_ENV=production
APP_KEY=base64:...
APP_URL=https://growuppro.com.br
APP_LOCALE=pt_BR
APP_DEBUG=false

# Database (Central)
DB_CONNECTION=mysql
DB_HOST=database
DB_PORT=3306
DB_DATABASE=growuppro_central
DB_USERNAME=growuppro
DB_PASSWORD=secure_password

# Tenancy
TENANCY_DATABASE_PREFIX=tenant_
CENTRAL_DOMAINS=growuppro.com.br

# Redis
REDIS_HOST=redis
REDIS_PASSWORD=null
REDIS_PORT=6379

# Cache & Queue
CACHE_DRIVER=redis
QUEUE_CONNECTION=redis
SESSION_DRIVER=redis

# Sentry (Error Tracking)
SENTRY_LARAVEL_DSN=https://xxx@sentry.io/xxx
SENTRY_TRACES_SAMPLE_RATE=0.2
SENTRY_PROFILES_SAMPLE_RATE=0.2

# Gitea Container Registry (or GitHub Container Registry as fallback)
REGISTRY_URL=gitea.yourdomain.com
REGISTRY_USERNAME=cauefaleiros
REGISTRY_PASSWORD=...  # Or use token

# GitHub Container Registry (GHCR) - if using as fallback
GHCR_TOKEN=ghp_...
GHCR_USERNAME=cauefaleiros
GHCR_IMAGE=ghcr.io/cauefaleiros/growup-pro

# Portainer
PORTAINER_URL=https://148.230.76.122:9443
PORTAINER_API_TOKEN=ptr_...
PORTAINER_STACK_ID=...

# Cloudflare (Optional - for API integration)
CLOUDFLARE_API_TOKEN=...
CLOUDFLARE_ZONE_ID=...
```

## Admin Dashboard for Tenant Management

The platform includes a basic admin dashboard for managing tenants.

### Current Implementation (MVP)
- **Route**: `/super-admin` (protected by `super_admin` middleware)
- **Features**: 
    - Basic Tenant CRUD (Create, Read, Update, Delete)
    - Session management (Login/Logout)
- **Tech Stack**: Custom Blade views (`resources/views/super-admin`) + Bootstrap/Tailwind (inherited)

### Pending Features (Roadmap)

**Analytics & Monitoring:**
- Total active tenants count
- Growth metrics (new tenants per month)
- Resource utilization per tenant
- Most active tenants (by usage)
- System health overview

**Enhanced Tenant Management:**
- View tenant resource usage (storage, bandwidth, users)
- Manage tenant subscriptions and billing
- Suspend or activate tenant access

**Bulk Operations:**
- Bulk tenant creation via CSV import
- Batch notifications to multiple tenants
- Mass configuration updates
- Export tenant data for reporting

**System Settings:**
- Default tenant configurations
- Resource limits and quotas
- Email templates for tenant communications
- Feature flags management
- Maintenance mode per tenant

### Implementation Notes
- Currently built with custom Blade views.
- **Future Upgrade**: Consider migrating to Filament Admin Panel for richer UI/UX.
- **Security**: Route protected by `super_admin` middleware.
- **Audit**: Need to implement audit logs for admin actions.

## Notes for Gemini AI Assistant

### Context Awareness
- This is **Growup Pro**, not Krayin - always use correct branding
- All text should be in **Portuguese (pt-BR)** when user-facing
- Consider **tenant context** in all suggestions
- Respect **Docker/Swarm constraints** in infrastructure suggestions

### Code Suggestions
- Prefer extending over modifying Krayin core
- Ensure **tenant isolation** in all data operations
- Follow **Tenancy for Laravel best practices**
- Include proper **error handling** (tenant not found, DB connection issues)
- Suggest **Docker-compatible** solutions (env vars, volumes, etc.)
- Always consider **Sentry error tracking** when suggesting error handling
- Recommend **testable code** (dependency injection, mockable services)
- Suggest **code quality improvements** when reviewing code (PHPStan compliance)

### Infrastructure Suggestions
- Consider **Docker Swarm** constraints (secrets, configs, networks)
- Suggest **zero-downtime** deployment strategies
- Include **health checks** in Docker configurations
- Recommend **scalable** solutions (horizontal scaling, load balancing)

### Translation Reminders
- Always provide Portuguese translations for new strings
- Check existing translation files before adding new keys
- Maintain consistent terminology across the application

## Quality Assurance & Best Practices

### Code Quality Tools
The project enforces code quality through automated tools:

**PHPStan (Static Analysis):**
- Level 5 minimum (configurable in `phpstan.neon`)
- Catches type errors, undefined variables, incorrect method calls
- Runs on every commit (pre-commit hook)
- Must pass before deployment

**Laravel Pint (Code Formatter):**
- PSR-12 coding standard enforcement
- Automatic code formatting
- Consistent code style across the team
- Can auto-fix issues: `./vendor/bin/pint`

**Pre-commit Hooks:**
- Automatically run before every commit
- Prevents committing code that doesn't pass quality checks
- Fast feedback loop for developers
- Configured via Husky or similar

### Error Tracking with Sentry

**Setup:**
```bash
composer require sentry/sentry-laravel
php artisan sentry:publish --dsn
```

**Features:**
- Real-time error notifications
- Complete stack traces with context
- User tracking (which tenant experienced the error)
- Performance monitoring
- Release tracking (know which deployment introduced bugs)

**Configuration:**
```php
// config/sentry.php
'dsn' => env('SENTRY_LARAVEL_DSN'),
'environment' => env('APP_ENV'),
'traces_sample_rate' => 0.2, // 20% of requests
'profiles_sample_rate' => 0.2,
```

**Tenant Context:**
Always include tenant information in Sentry reports:
```php
\Sentry\configureScope(function (\Sentry\State\Scope $scope): void {
    $scope->setTag('tenant_id', tenant('id'));
    $scope->setContext('tenant', [
        'name' => tenant('name'),
        'domain' => tenant('domain'),
    ]);
});
```

### Testing Standards
- **Coverage minimum**: 70% code coverage
- **Test pyramid**: More unit tests, fewer integration/feature tests
- **Tenant isolation tests**: Critical - must verify data doesn't leak
- **Performance tests**: Ensure queries are optimized (N+1 detection)
- **CI enforcement**: All tests must pass before merge

## Resources & Documentation

### Project Specific
- [Krayin CRM Docs](https://devdocs.krayincrm.com/)
- [Krayin GitHub](https://github.com/krayin/laravel-crm)
- [Tenancy for Laravel Docs](https://tenancyforlaravel.com/docs/v3/introduction)

### Infrastructure
- [Docker Documentation](https://docs.docker.com/)
- [Docker Compose Reference](https://docs.docker.com/compose/compose-file/)
- [Docker Swarm Guide](https://docs.docker.com/engine/swarm/)
- [Portainer Documentation](https://docs.portainer.io/)
- [Portainer API Reference](https://docs.portainer.io/api/docs)

### CI/CD
- [Gitea Actions Documentation](https://docs.gitea.com/usage/actions/overview)
- [Gitea Actions Quickstart](https://docs.gitea.com/usage/actions/quickstart)
- [act_runner Documentation](https://gitea.com/gitea/act_runner)
- [GitHub Actions (for compatibility reference)](https://docs.github.com/en/actions)
- [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)
- [Docker Build Actions](https://github.com/docker/build-push-action)

### Laravel & PHP
- [Laravel Documentation](https://laravel.com/docs)
- [Laravel Multi-tenancy Patterns](https://laravel-news.com/multi-tenancy)
- [PSR-12 Coding Standard](https://www.php-fig.org/psr/psr-12/)

---

**Project**: Growup Pro  
**Base**: Krayin Laravel CRM (Whitelabel)  
**Current Phase**: Initial setup - multi-tenancy integration and Docker infrastructure  
**Domain**: growuppro.com.br  
**Language**: Portuguese (pt-BR)  
**Deployment**: Docker Swarm + Portainer + GitHub Actions CI/CD