#Technical Guide

Relaticle is built on the Laravel 12 framework with Filament 3 for the admin panel interface. The front-end uses Livewire and Tailwind CSS to create a responsive and interactive user experience.

  • Backend: PHP 8.3, Laravel 12
  • Admin UI: Filament 3
  • Frontend: Livewire, Tailwind CSS, Alpine.js
  • Database: PostgreSQL (recommended), MySQL (supported)
  • Testing: Pest
  • Static Analysis: PHPStan
  • Code Quality: Laravel Pint, Rector
  • Task Queue: Laravel Horizon
  • Authentication: Laravel Jetstream, Laravel Fortify
  • Error Tracking: Sentry integration

Relaticle includes one premium component:

Custom Fields - A FilamentPHP plugin that enables unlimited custom fields on any Laravel model without database migrations.

  • License: AGPL-3.0 (free for open source) or Commercial license (required for proprietary projects)
  • Documentation: custom-fields.relaticle.com

This is the only paid component in Relaticle, helping sustain the open-source project.

Relaticle's data structure revolves around these key models:

  • Team: The organizational unit that groups users together
  • User: System users with authentication and permissions
  • Company: Organizations your business interacts with
  • People: Individual contacts at companies
  • Opportunity: Potential deals in the sales pipeline
  • Task: Actionable items assigned to users
  • Note: Documentation of interactions and important information
  • Teams have many Users (through Memberships)
  • Companies belong to Teams
  • Companies have many People
  • Companies have many Opportunities
  • People belong to Companies
  • Opportunities belong to Companies
  • Tasks can be associated with various models (polymorphic)
  • Notes can be associated with various models (polymorphic)

To develop Relaticle locally, you'll need:

  • PHP 8.3+ with the following extensions:
    • pdo_pgsql (or pdo_mysql)
    • gd
    • bcmath
    • ctype
    • fileinfo
    • json
    • mbstring
    • openssl
    • tokenizer
    • xml
  • PostgreSQL 13+ (recommended) or MySQL 8.0+
  • Node.js 16+ with npm
  • Composer 2+
  1. Clone the repository
  1. Install dependencies
  1. Configure environment

Open the .env file and configure your database connection:

  1. Run migrations
  1. Link storage
  1. Start development services

In separate terminal windows, run:

Visit http://localhost:8000 in your browser to access the application.

Note: By default, emails are sent to the log driver. You can change this in the .env file to something like mailtrap for development.

Relaticle follows Laravel's coding standards and conventions. We enforce these through:

  • Laravel Pint: Ensures consistent code styling
  • Rector: Refactors code to use modern PHP features
  • PHPStan: Validates type correctness and prevents common issues
  • Pest: Ensures code quality through comprehensive tests

Relaticle uses several tools to maintain code quality:

Pull requests that don't pass the test suite will not be merged. Always run composer test before submitting your changes.

Relaticle uses Git Hooks to automate quality checks during the development process. The hooks are located in the .githooks directory, and you can enable them by running:

This will automatically run the appropriate checks when you commit or push code.

All code contributions should include:

  • Unit tests for new functionality
  • Feature tests for user interactions
  • Passing static analysis checks
  • Minimum 99.6% type coverage

When adding new features:

  1. Start by creating the necessary models and migrations
  2. Implement business logic in dedicated Service classes
  3. Create Filament resources for admin panel integration
  4. Add Livewire components for frontend interactions
  5. Write comprehensive tests
  6. Document the feature in relevant documentation

The Filament ecosystem makes it easy to create custom components. Here's an example of a Filament resource:

  • Use eager loading to prevent N+1 query issues
  • Keep frontend dependencies minimal
  • Optimize database indexes for common queries
  • Use Laravel queues for processing background tasks
  • Implement caching for expensive operations
  • Consider database query optimization for large datasets
  • Set up proper indexing for search functionality
  • All user input must be validated
  • Follow Laravel's authentication and authorization patterns
  • Implement proper CSRF protection
  • Use Laravel Sanctum for API authentication
  • Regularly update dependencies for security patches
  • Implement rate limiting for sensitive endpoints
  • Follow the principle of the least privilege for user permissions
  • Properly sanitize user inputs, especially for database queries
  1. Configure environment-specific variables
  2. Set up a production database with proper credentials
  3. Configure a robust caching system (Redis recommended)
  4. Set up a queue worker using Supervisor
  5. Configure a web server (Nginx recommended)
  6. Set up SSL certificates
  7. Configure proper backups
  8. Set up monitoring tools
  1. Pull latest code from the repository
  2. Install production dependencies: composer install --no-dev --optimize-autoloader
  3. Build frontend assets: npm ci && npm run build
  4. Run migrations: php artisan migrate --force
  5. Clear and rebuild caches: php artisan optimize
  6. Restart queue workers: php artisan queue:restart
  • PHP 8.3+ with required extensions
  • PostgreSQL 13+ or MySQL 8.0+
  • Redis (recommended for caching and queues)
  • Nginx or Apache
  • Supervisor (for managing queue workers)

Ensure proper permissions on the storage directory:

Use Laravel Telescope or Clockwork to identify slow queries, then add appropriate indexes.

  1. Verify the license is active
  2. Check that the package is properly installed: composer require relaticle/custom-fields
  1. Clear the view cache: php artisan view:clear
  2. Rebuild the assets: npm run build
  3. Check browser console for JavaScript errors

We welcome contributions from developers of all skill levels! Relaticle is an open-source project that thrives on community involvement.

  1. Fork the repository on GitHub
  2. Create a feature branch: git checkout -b feat/amazing-feature or fix/your-fix
  3. Make your changes following our coding standards outlined in the Development Guidelines section
  4. Run tests to ensure quality: composer test
  5. Commit your changes with descriptive messages following conventional commits
  6. Push to your branch: git push origin feat/amazing-feature
  7. Create a Pull Request and explain your changes clearly
  • Bug fixes - Help us improve stability
  • Feature additions - Implement new capabilities
  • Documentation improvements - Enhance guides and examples
  • Test coverage - Add or improve tests
  • UI/UX enhancements - Improve the user experience

We strive to maintain a welcoming and inclusive environment for all contributors. Please be respectful in all interactions and focus on constructive feedback.

Remember that all contributions to Relaticle are subject to review and must align with the project's goals and quality standards. Working closely with maintainers will help ensure your contribution is accepted and merged efficiently.