Development

This guide covers the development workflow, available commands, project structure, and deployment process for Personal CRM.

Development Commands

Server & Assets

# Start the local development server on http://localhost:8000
php artisan serve

Database

# Run pending database migrations
php artisan migrate

Queue & Background Jobs

# Process queued jobs (month generation, balance recalculation)
php artisan queue:work

Custom Artisan Commands

# Manually trigger balance recalculation for all months
php artisan app:recalculate-months

Testing & Code Quality

# Run the PHP test suite
php artisan test

Debugging

# Stream application logs in real-time
php artisan pail

Project Structure

Application Core

app/Models/ — Eloquent models: User, Year, Month, Period, Task, Payment, Requirement, Specification, Decision, Product, MonthPeriod, Role.
app/Enums/ — PHP enums: PaymentType, PaymentStatus, PaymentCategory, TaskPriority, TaskStatus.
app/Observers/ — Eloquent observers for auto-setting user ownership on model creation.
app/Policies/ — Authorization policies for model-level access control.
app/Providers/ — Service providers: AppServiceProvider, Filament AdminPanelProvider.

Filament Admin Panel

app/Filament/Resources/ — Filament CRUD resources with form schemas, table definitions, and relation managers.
app/Filament/Widgets/ — Dashboard widgets: StatsOverview, MonthsChart, YearsChart, TodayDateWidget.
app/Filament/Pages/ — Custom Filament pages: BillingInformation, ContactForm.

HTTP Layer

app/Http/Controllers/ — Web controllers: SubscriptionController.
app/Http/Middleware/ — Custom middleware: Subscribed, Customer.

Background Processing

app/Jobs/ — Queue jobs: GenerateMonthsJob, RecalculateMonthsJob, AutoCompleteMonthsJob, CleanMonthsPaymentsJob.
app/Console/Commands/ — Artisan commands for maintenance and data operations.

Database

database/migrations/ — Database schema migrations for all tables.
database/seeders/ — Database seeders: RoleSeeder, DatabaseSeeder.

Frontend

resources/views/ — Blade templates for landing page, Filament custom views, email templates, and layout components.
resources/css/ — Tailwind CSS source files.
resources/js/ — JavaScript entry point and modules.

Configuration & Routing

routes/web.php — Web routes: landing page, subscription checkout, billing portal.
routes/console.php — Console routes: scheduled health checks and backup commands.
config/ — Laravel configuration files for app, database, cache, queue, mail, Stripe, permissions, health, etc.

CI/CD & Deployment

tests/ — PHP and JavaScript test files.
.github/workflows/ — GitHub Actions CI/CD: lint.yml (PHP Pint, ESLint, Prettier), tests.yml.
Envoy.blade.php — Laravel Envoy deployment task runner configuration.

Deployment

Ensure the target server meets all system requirements: PHP 8.2+, MySQL 8.0+, Node.js 18+, and Composer 2.x. Set APP_ENV=production and APP_DEBUG=false in your production environment.

Using Laravel Envoy

Configure the deployment variables in your CI/CD environment, then run:

# Deploy via Laravel Envoy (handles git pull, composer install,
# migrations, asset building, cache clearing, and queue restart)
envoy run deploy

Required CI/CD variables: DEPLOY_USER, DEPLOY_HOST, DEPLOY_REPOSITORY, DEPLOY_APP_DIR, DEPLOY_BRANCH.

Manual Deployment

git pull
composer install --no-dev --optimize-autoloader
npm ci && npm run build
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

Post-Deployment Steps

Stripe Webhook — Set up the Stripe webhook endpoint in your Stripe Dashboard pointing to https://yourdomain.com/stripe/webhook.
Process Manager — Configure Supervisor to run:
- php artisan horizon (queue worker)
- php artisan schedule:run (cron scheduler)
Cron Entry — Add the Laravel scheduler to your crontab:

* * * * * cd /path-to-project && php artisan schedule:run >> /dev/null 2>&1

Web Server — Configure your web server (Nginx/Apache) to point the document root to the /public directory.
File Permissions — Ensure storage/ and bootstrap/cache/ directories are writable by the web server.
Health Check — Verify everything is working:

php artisan health:check

Monitoring — Monitor the application via Sentry (errors), Horizon dashboard (queues), and the built-in health check page at /app/health-check-results.