DOCSEARCHbyAlgolia
Submit Docs

ERPSAAS Documentation

repository·3.x·Indexed 23 days ago

https://github.com/andrewdwallo/erpsaas

A Laravel and Filament-powered accounting platform for professional financial management using full double-entry accrual accounting. Features include PDF report generation via Wkhtmltopdf, real-time currency exchange rates through ExchangeRate-API, and financial data connectivity via Plaid integration.

Tokens
3.1K
Snippets
9
Records
18
Agent score
81%

What's inside ERPSAAS

  1. Integrate Plaid for financial data connectivity

    3.x

    To connect bank accounts and import transactions, configure Plaid in your .env file:

    PLAID_CLIENT_ID=your-client-id
PLAID_CLIENT_SECRET=your-secret
PLAID_ENVIRONMENT=sandbox # sandbox, development, or production
PLAID_WEBHOOK_URL=https://your-static-domain.com/api/plaid/webhook

    Important:

    • PLAID_WEBHOOK_URL must end with /api/plaid/webhook and use a static domain (e.g., via ngrok).
    • After connecting an account on the "Connected Accounts" page, you must run the following command to process queued transactions: php artisan queue:listen
    PLAID_CLIENT_ID=your-client-id
PLAID_CLIENT_SECRET=your-secret
PLAID_ENVIRONMENT=sandbox
PLAID_WEBHOOK_URL=https://my-static-domain.ngrok-free.app/api/plaid/webhook

  2. Configure PDF report generation with Wkhtmltopdf

    3.x

    ERPSAAS uses Laravel Snappy to generate PDF reports. While the package is included, you must install the wkhtmltopdf binary on your system.

    1. Install Wkhtmltopdf:
      • macOS (Homebrew): brew install wkhtmltopdf
      • Other: Download from wkhtmltopdf.org.
    2. Configure Paths: If the binary is not in your standard path, update the configuration in config/snappy.php.
    brew install wkhtmltopdf

  3. Install ERPSAAS

    3.x

    Follow these steps to set up the ERPSAAS development environment. Ensure you meet the server requirements specified in the official Laravel documentation before starting.

    1. Clone the repository: git clone https://github.com/andrewdwallo/erpsaas.git
    2. Navigate to the directory: cd erpsaas
    3. Install PHP and JS dependencies: composer install npm install
    4. Configure environment variables: cp .env.example .env (Edit .env to configure your database connection)
    5. Generate application key: php artisan key:generate
    6. Run database migrations: php artisan migrate
    7. Build assets and start the server: php artisan filament:assets npm run build npm run dev
    git clone https://github.com/andrewdwallo/erpsaas.git
cd erpsaas
composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate
npm run build
npm run dev

  4. Set up the testing environment with Pest

    3.x

    ERPSAAS uses Pest for testing.

    1. Create Test Database: Create a separate database named erpsaas_test in your database manager (e.g., MySQL). CREATE DATABASE erpsaas_test;
    2. Run Tests: The test suite automatically handles refreshing and seeding the erpsaas_test database. No manual migrations are required for the test database.
    CREATE DATABASE erpsaas_test;

  5. Enable and configure Live Currency exchange rates

    3.x

    The Live Currency feature provides real-time exchange rates via ExchangeRate-API. This feature is disabled by default.

    1. Setup API Key

    Register at ExchangeRate-API and add your key to the .env file: CURRENCY_API_KEY=your_api_key

    2. Initialize Database

    Run a fresh migration and initialize the currency list:

    php artisan migrate:fresh
php artisan currency:init

    3. Customizing the Service

    To use a different provider, update config/services.php:

    'currency_api' => [
    'key' => env('CURRENCY_API_KEY'),
    'base_url' => 'https://v6.exchangerate-api.com/v6',
],

    Then, adjust the implementation in App\Services\CurrencyService to match your provider's API.

  6. Populate the database with seed data

    3.x

    To quickly populate your database with initial data, you can use the built-in seeder.

    1. Customize Seeder (Optional): Open database/seeders/DatabaseSeeder.php to set specific property values.
    2. Default Credentials: If using default seed data, log in with:
      • Email: admin@erpsaas.com
      • Password: password
    3. Run Seeder: Execute php artisan db:seed.

    Note: It is recommended to use a clean database. You can reset your database state using php artisan migrate:fresh before seeding.

    php artisan db:seed

  7. Client Model Relationships

    3.x

    The Client model serves as a central hub for customer data and connects to several other modules via Eloquent relationships:

    Contacts

    • primaryContact(): Returns the single Contact assigned as the primary contact (is_primary: true).
    • secondaryContacts(): Returns a collection of Contact models where is_primary is false.
    • contacts(): Returns all associated Contact models via a morph relationship.

    Addresses

    • billingAddress(): Returns the single Address associated with AddressType::Billing.
    • shippingAddress(): Returns the single Address associated with AddressType::Shipping.
    • addresses(): Returns all associated Address models via a morph relationship.

    Accounting & Financials

    • currency(): Returns the Currency model associated with the client's currency_code.
    • transactions(): Returns all Transaction records where the client is the payee (payeeable morph).
    • estimates(): Returns all Estimate models belonging to the client.
    • invoices(): Returns all Invoice models belonging to the client.
    • recurringInvoices(): Returns all RecurringInvoice models belonging to the client.

  8. Configure core application settings in app.php

    3.x

    The config/app.php file defines the core behavior of the ERPSAAS application. Most settings are driven by environment variables defined in your .env file. Use these settings to control the application's identity, environment, security, and localization.

    Key Configuration Categories

    Identity and Environment

    • name: The application name used in notifications and UI elements.
    • env: The current environment (e.g., production, local).
    • debug: Boolean flag to enable/disable detailed error messages and stack traces.
    • url: The root URL used by the Artisan CLI to generate absolute URLs.

    Localization and Time

    • timezone: The default timezone for PHP date/time functions (defaults to UTC).
    • locale: The default locale for translation/localization methods.
    • fallback_locale: The locale used when a translation is missing in the primary locale.
    • faker_locale: The locale used by the Faker library for generating dummy data.

    Security

    • cipher: The encryption algorithm used (defaults to AES-256-CBC).
    • key: The primary encryption key. This must be a random 32-character string.
    • previous_keys: An array of keys used to decrypt data encrypted with older keys. This is populated from a comma-separated list in the APP_PREVIOUS_KEYS environment variable.

  9. Configure maintenance mode drivers

    3.x

    The maintenance configuration determines how the application manages its 'maintenance mode' status. This is useful for taking the application offline for updates.

    • driver: Specifies the driver used to manage maintenance mode. Supported values are file and cache. Using the cache driver allows maintenance mode to be synchronized across multiple machines.
    • store: Specifies where the maintenance state is stored (e.g., database).
    'maintenance' => [
    'driver' => env('APP_MAINTENANCE_DRIVER', 'file'),
    'store' => env('APP_MAINTENANCE_STORE', 'database'),
],

  10. Update a Client with relations using updateWithRelations()

    3.x

    The updateWithRelations(array $data) method updates an existing Client instance and synchronizes its related models.

    Key behaviors:

    • Primary Contact: Updates or creates the contact where is_primary is true.
    • Secondary Contacts: Synchronizes the list. It deletes contacts not present in the provided $data['secondaryContacts'] array and updates or creates the remaining ones.
    • Billing Address: Updates or creates the address with AddressType::Billing.
    • Shipping Address: Updates or creates the address with AddressType::Shipping. If same_as_billing is set to true in the data, it will copy the values from the client's current billing address into the shipping address record.

    This method returns the updated Client instance.

  11. Create a Client with relations using createWithRelations()

    3.x

    The Client::createWithRelations(array $data) static method allows you to create a new client and its associated related data (primary contact, secondary contacts, billing address, and shipping address) in a single operation.

    Expected keys in the $data array:

    • company_id (required)
    • name (required)
    • currency_code (optional)
    • account_number (optional)
    • website (optional)
    • notes (optional)
    • primaryContact (optional): An array containing first_name, last_name, email, and phones (array).
    • secondaryContacts (optional): An array of contact arrays, each containing first_name, last_name, email, and phones (array).
    • billingAddress (optional): An array containing address_line_1, address_line_2, country_code, state_id, city, and postal_code.
    • shippingAddress (optional): An array containing recipient, phone, notes, address_line_1, address_line_2, country_code, state_id, city, postal_code, and a boolean same_as_billing.