Goodwork Laravel Package

Getting Started

GoodWork is a complete Laravel application, not an installable Composer package — you don't composer require it into an existing project. "Getting started" means standing up your own fork.

git clone https://github.com/iluminar/goodwork.git
cd goodwork
composer install
cp .env.example .env
php artisan key:generate
# configure DB_* in .env (MySQL or PostgreSQL)
php artisan migrate --seed
npm install && npm run build
php artisan serve

Where to look first, in order:

1. composer.json — confirms the Laravel and Filament major versions you're pinned to. Everything downstream depends on this.
2. app/Filament/ — the admin UI is almost entirely Filament Resources; this is where 80% of day-to-day changes land.
3. app/Models/ — Client, Project, Task, TimeEntry, Invoice and their relationships define the domain.
4. database/migrations/ and database/seeders/ — the schema you'll be extending, plus demo data to click through.
5. config/ — currency, tax, and mail settings that bite later.

First use case to validate the install: create a Client → Project → Task, log a TimeEntry against it, then generate an Invoice from tracked time. If that loop works end-to-end (including PDF output), your environment is correct.

Implementation Patterns

Treat it as a starter SaaS, not a dependency. The realistic workflow is fork → rebrand → extend. Keep a clean upstream remote so you can cherry-pick fixes:

git remote add upstream https://github.com/iluminar/goodwork.git
git fetch upstream && git log --oneline upstream/master ^master

Extending the UI via Filament Resources. Custom fields, new columns, and workflow buttons are added by overriding the Resource's form() / table() schema rather than editing Blade. Prefer creating your own Resource in app/Filament/Resources/ and adjusting navigation/permissions, so upgrades touch fewer files.

Schema extension pattern. Add migrations for your fields (php artisan make:migration add_x_to_projects), add the column to the model's $fillable/$casts, then surface it in the Filament form. This trio (migration + model + Resource) is the unit of work for most customizations.

Time tracking and invoicing as the integration seam. Time entries roll up into invoice line items. If you need custom billing rules (rounding, billable rates per role, retainers), implement them as a service class invoked at invoice generation time, not inside the Resource — keeps logic testable and reusable from a command or job.

Background work. Invoice PDF rendering, mail, and any exports should run on queues. Add a queue worker (Supervisor or a container sidecar) and set QUEUE_CONNECTION to Redis/database rather than sync in production.

Deployment. It's a standard Laravel app: Nginx + PHP-FPM, php artisan migrate --force, config:cache, route:cache, view:cache, storage symlink, and a scheduler cron entry. Docker/Forge/Vapor all work; nothing GoodWork-specific is required.

Integration tips. For external systems (accounting, CRMs), prefer Artisan commands + scheduling over hacking controllers, and use model observers on Invoice/TimeEntry to push events outward. If you need an API for a mobile client, add routes in a dedicated routes/api.php guarded by Sanctum rather than reusing web routes.

Gotchas and Tips

• No upstream package updates. You own the entire codebase forever. Every Laravel/Filament security release is your migration. Budget for this before adopting.
• Filament version lock is the hardest constraint. Check composer.json first; customizing Resources against v3 while upstream moves on creates painful merge conflicts. Pin Filament and upgrade deliberately, reading the upgrade guide.
• Fork drift. Every file you edit in app/Filament is a future conflict. Prefer new Resources, Filament plugins, and service classes over in-place edits to core files.
• PDF generation dependencies. Invoice rendering often needs dompdf/wkhtmltopdf/Browsershot. Verify the binary/extension exists in your container image — this is the most common "works locally, fails in prod" failure.
• Timezone handling. Store timestamps in UTC and render per-user timezone. Time entries crossing midnight are a classic source of wrong hours on invoices; test with a non-UTC user.
• Currency and tax config. Set these at install time. Changing the base currency later does not retroactively convert historical invoices — decide before you generate real data.
• Seeder data is demo data. Don't run --seed in production; audit the seeders for hardcoded admin credentials and sample clients.
• Permissions. If the app uses a roles/permissions layer, verify policies on new Resources explicitly — Filament will happily render a nav item for a user who can't use it.
• Debugging. Filament form/table issues are almost always schema-level, not Blade-level. Use php artisan about, check storage/logs/laravel.log, and php artisan filament:optimize-clear after resource changes.
• Extension points worth knowing: Filament plugins (auth, media, settings), custom Pages for dashboards, model observers for side effects, and Artisan commands for reports/exports. These give you leverage without forking core logic.