Architecture

Personal CRM follows a layered MVC architecture built on Laravel 12. The admin interface is powered by Filament 3, which provides auto-discovered CRUD resources with Livewire-based reactive components. Data is stored in MySQL with polymorphic relationships enabling flexible entity attachment. Background processing uses Laravel's queue system with database driver, monitored by Horizon. User scoping ensures multi-tenant data isolation, and Stripe handles all billing operations.

Overview

The application is structured around several key architectural decisions:

MVC with Filament — Laravel provides the model and controller layers, while Filament 3 handles the view layer with auto-discovered CRUD resources and Livewire-based reactive components.
Polymorphic Relationships — Tasks, payments, requirements, and specifications can be attached to any parent entity (months, years, periods) through polymorphic relations, enabling maximum flexibility.
Queue-Based Processing — Heavy operations like month generation and balance recalculation run as background jobs, keeping the UI responsive.
Multi-Tenant Isolation — Eloquent observers auto-assign user_id on model creation, and policies enforce that users can only access their own data.
SaaS Billing — Laravel Cashier integrates with Stripe for subscription management, with middleware enforcing active subscription or trial status.

Modules

Models

app/Models/

Eloquent models defining data structure and relationships: User, Year, Month, Period, Task, Payment, Requirement, Specification, Decision, Product, MonthPeriod, Role.

Filament Resources

app/Filament/Resources/

CRUD admin interfaces for each entity: YearResource, MonthResource, PeriodResource, PaymentResource, ProductResource, UserResource, RoleResource, ActivityResource.

Relation Managers

app/Filament/Resources/*/RelationManagers/

Polymorphic child management within parent resources: TasksRelationManager, PaymentsRelationManager, SpecificationsRelationManager, RequirementsRelationManager, MonthsRelationManager.

Filament Pages

app/Filament/Pages/

Custom admin pages: Financial Calendar, Billing Information, Contact Form, Health Check Results, View Log.

Filament Widgets

app/Filament/Widgets/

Dashboard widgets: StatsOverview (financial totals), MonthsChart (monthly bar chart), YearsChart (annual trends), TodayDateWidget.

Observers

app/Observers/

Eloquent observers that auto-set user_id on model creation for: Year, Month, Period, Task, Payment, Requirement, Specification, Decision.

Jobs

app/Jobs/

Queue jobs for async operations: GenerateMonthsJob (creates 12 months for a year), RecalculateMonthsJob (recalculates balances), AutoCompleteMonthsJob (populates standard payments), CleanMonthsPaymentsJob.

Commands

app/Console/Commands/

Artisan CLI commands: auto-complete-months, complete-limit-timestamps, recalculate-months, custom-auto-complete-months.

Enums

app/Enums/

PHP enums for type safety: PaymentType (Income, Expense), PaymentStatus (Pending, Completed, Cancelled, Refunded), PaymentCategory (OneTime, Recurring), TaskPriority (Low, Medium, High, Urgent), TaskStatus (Reported, InProgress, Completed, Abandoned).

Middleware

app/Http/Middleware/

Custom middleware: Subscribed (validates active subscription or trial), Customer (verifies customer role).

Controllers

app/Http/Controllers/

Web controllers: SubscriptionController (handles Stripe checkout and billing portal redirects).

Migrations & Seeders

database/migrations/ and database/seeders/

Database schema definitions for all tables. Seeders: RoleSeeder (creates Super Admin and Customer roles), DatabaseSeeder (orchestrates all seeders).

Views

resources/views/

Blade templates: welcome (landing page), Filament resource views (financial calendar, stats overview, billing, contact form), email templates, layout components.

The application uses a sidebar navigation within the /app admin panel, organized into logical groups. Public pages are accessible without authentication.

Main

Core planning and management modules.

Name
/app
Type
Dashboard
Description
Central hub with financial stats overview widget (current, business, economies amounts and minimums), monthly balance bar chart, yearly trend chart, and today's date display.
Name
/app/months
Type
Months
Description
Browse, create, and edit monthly plans. Each month detail page has tabs for payments, tasks, requirements, and specifications via relation managers.
Name
/app/periods
Type
Periods
Description
Define custom recurring schedules. Attach periods to months via many-to-many relationships. Manage associated tasks and specifications. Supports drag-and-drop reordering.
Name
/app/years
Type
Years
Description
Annual planning hub. Creating a year auto-generates 12 months. View and edit months within a year. Access the Financial Calendar from the year detail page header action.
Name
/app/years/{id}/financial-calendar
Type
Financial Calendar
Description
Visual year overview displaying all 12 months as color-coded cards. Green for positive net income, red for negative. Shows income and expense totals per month.

Secondary

Supporting financial management modules.

Name
/app/payments
Type
Payments
Description
Manage recurring payments globally. One-time payments are managed within their parent entity (month, year, etc.) via relation managers.

Shop

Subscription and product management.

Name
/app/products
Type
Products
Description
Subscription product catalog. Define Stripe product IDs, pricing, feature lists (JSON array), and descriptions. Products support soft deletes.

Settings

Admin-only system management and monitoring (requires Super Admin role).

Name
/app/users
Type
User Management
Description
Manage user accounts, assign roles (Super Admin, Customer), configure per-user currency and financial settings (current_amount, business_amount, economies_amount with minimums).
Name
/app/roles
Type
Roles
Description
Manage roles and permissions via Spatie Permissions. Default roles: Super Admin (full access) and Customer (subscription-gated access).
Name
/app/activities
Type
Activity Log
Description
Filterable audit trail of all model changes. Shows subject, causer, event type, and before/after attribute values.
Name
/app/health-check-results
Type
Health Checks
Description
Live system health dashboard checking database connectivity, disk space, debug mode status, environment correctness, Horizon status, and scheduler status.
Name
/app/view-log
Type
View Log
Description
Browse application log files directly from the admin panel.

Account

User account and billing pages.

Name
/app/billing-information
Type
Billing Information
Description
View current subscription status, manage trial periods (add, cancel, extend), and access the Stripe billing portal for payment method and invoice management.
Name
/app/contact-form
Type
Contact Form
Description
Submit support requests directly from the admin panel. Sends an email notification to the configured support address.
Name
/app/profile
Type
Profile
Description
Update personal information (name, email) and change password. Accessible from the user dropdown menu in the top-right corner of the panel.

Public

Pages accessible without authentication.

Name
/
Type
Landing Page
Description
Public marketing page with hero section, feature showcase, pricing cards, testimonials, and FAQ accordion. Entry point for new users.
Name
/app/register
Type
Registration
Description
New user sign-up form with name, email, and password. After registration, users are redirected to the admin panel dashboard.
Name
/app/login
Type
Login
Description
User authentication page with email and password. Includes password reset link.
Name
/subscription/buy/{product}
Type
Subscription Checkout
Description
Initiates Stripe checkout session for the selected subscription product. Redirects to Stripe-hosted payment page.
Name
/subscription/billing-portal
Type
Billing Portal
Description
Redirects authenticated customers to the Stripe-hosted billing portal for invoice history and payment method management.