Getting Started

Follow these steps to get Personal CRM up and running on your local machine. This guide covers installation, environment configuration, and an overview of the basic usage flow.

Installation

Clone the repository and install all dependencies:

git clone <repository-url> personal-crm && cd personal-crm
composer install
npm install

After running php artisan serve, access the application at http://localhost:8000 for the landing page or http://localhost:8000/app for the admin panel.

Configuration

Once the environment file is created, configure the following:

1. Set your database credentials (DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD) in the .env file.
2. Configure Stripe keys from your Stripe Dashboard (Developers > API keys): STRIPE_KEY, STRIPE_SECRET, STRIPE_WEBHOOK_SECRET.
3. Set up a Stripe webhook endpoint pointing to /stripe/webhook with events: customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.payment_succeeded.
4. Configure mail settings for transactional emails (contact form, notifications).
5. Set APP_ENV=production and APP_DEBUG=false for production deployments.
6. Optionally configure Sentry DSN for error monitoring.
7. Optionally configure AWS S3 credentials for file storage.

Environment Variables

Basic Usage Flow

Once the application is installed and configured, the typical workflow is:

1. Register a new account via the Filament registration page at /app/register.
2. Start a trial or subscribe to a plan via the billing page.
3. Create a new Year (e.g., 2027) — the system auto-generates 12 months.
4. Set the starting balance for the year.
5. Add recurring payments (income sources, regular expenses) to each month.
6. The system automatically calculates and propagates balances across all months.
7. Use the Financial Calendar to visualize your year at a glance.
8. Create tasks for projects and assign priorities, time estimates, and responsible persons.
9. Attach requirements and specifications to tasks or payments for documentation.
10. Track decisions made during task execution.
11. Monitor your financial overview via the dashboard widgets and charts.
12. Use the Activity Log to review all changes made to your data.

Examples

Planning a New Year

1. Navigate to Years in the sidebar.
2. Click Create Year and enter the year number (e.g., 2027).
3. Set the starting balance (your current account balance).
4. The system creates January through December automatically.
5. Open each month to add expected income and expenses.
6. View the Financial Calendar to see your projected balance trajectory.

Tracking Monthly Finances

1. Open a specific month from the sidebar or year view.
2. Add payments: specify name, amount, type (Income/Expense), status, and category.
3. The starting balance carries over from the previous month's final balance.
4. The final balance is automatically calculated: starting_balance + income - expenses.
5. Mark payments as Completed, Pending, Cancelled, or Refunded as they occur.

Managing Project Tasks

1. Open any month, year, or period resource.
2. Navigate to the Tasks tab in the relation manager.
3. Create tasks with name, priority (Low/Medium/High/Urgent), and estimated hours.
4. Assign an author and responsible person.
5. Update status as work progresses: Reported → In Progress → Completed.
6. Log actual time spent for comparison with estimates.
7. Add decisions within tasks to document choices made.

Using Periods for Recurring Schedules

1. Navigate to Periods in the sidebar.
2. Create a new period (e.g., "Q1 Sprint", "Monthly Review").
3. Attach the period to relevant months via the many-to-many relationship.
4. Add tasks and specifications to the period.
5. Reorder periods using drag-and-drop.