Development Guide

Generated: 2025-11-16

Prerequisites

Required Software

PHP 8.3+ (exact: 8.3.27)
Composer 2.x
Node.js 18+ (check .nvmrc)
NPM 10+
MySQL 8.0+
Redis (for queues/cache)

Recommended Tools

Laravel Valet (Mac/Linux) or Homestead (Windows)
Git 2.x
IDE: VS Code, PHPStorm, or Cursor

Local Setup

1. Clone Repository

git clone https://github.com/salthq/flowcode.git
cd flowcode

2. Install Dependencies

# PHP dependencies
composer install

# Node dependencies
npm install

3. Environment Configuration

# Copy example environment file
cp .env.example .env

# Generate application key
php artisan key:generate

Critical .env Variables:

APP_URL=https://flowcode.test

# Database
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=flowcode
DB_USERNAME=root
DB_PASSWORD=

# Redis (for queues/cache)
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Firebase Authentication
# Contact team lead for credentials

# AWS S3 (file storage)
# Contact team lead for credentials

4. Database Setup

# Run migrations
php artisan migrate

# Seed database with initial data
php artisan db:seed

5. Local Server Setup

Mac/Linux (Valet):

# Link project
valet link flowcode

# Enable HTTPS
valet secure flowcode

# Access at: https://flowcode.test

Windows (Homestead): Follow Laravel Homestead setup documentation.

6. Git Hooks

# Configure git hooks for code formatting
git config core.hooksPath .githooks

# Set permissions (Linux/Mac)
chmod ug+x .githooks/*

Development Workflow

Branch Strategy

Main Branch: develop
Feature Branches: feature/description
Bug Fixes: fix/description
Hotfixes: hotfix/description

# Start new feature
git checkout develop
git pull origin develop
git checkout -b feature/my-feature

Running the Application

# Start Vite dev server (frontend hot reload)
npm run dev

# Or build for production
npm run prod

Common Commands

# Clear all caches
php artisan optimize:clear

# Regenerate autoload
composer dump-autoload

# Run queue worker
php artisan queue:work

# Start Horizon dashboard
php artisan horizon

# View logs in Telescope
# Navigate to /telescope in browser (dev only)

Code Quality

PHP Formatting (Pint)

# Check formatting
vendor/bin/pint --test

# Fix formatting
vendor/bin/pint

# Fix only changed files
vendor/bin/pint --dirty

Frontend Linting

# ESLint
npx eslint resources/ts/

# Prettier
npx prettier --check resources/ts/

Pre-commit Hooks

Automatically runs on commit: - PHP: Laravel Pint - TypeScript: ESLint + Prettier

Testing

Running Tests

# All tests
php artisan test

# Specific file
php artisan test tests/Feature/ExampleTest.php

# Filter by name
php artisan test --filter=testName

# Parallel testing
php artisan test --parallel

Test Types

Feature Tests (tests/Feature/)
Integration testing
API endpoint testing
Workflow testing
Unit Tests (tests/Unit/)
Isolated unit testing
Model testing
Service testing
Browser Tests (tests/Browser/)
Laravel Dusk E2E testing
UI interaction testing

Pest Framework

Tests use Pest v4 (BDD-style):

it('creates a user', function () {
    $user = User::factory()->create();
    expect($user)->toBeInstanceOf(User::class);
});

Test Configuration

# Use testing database
cp .env.testing.example .env.testing

# Set up test database
php artisan migrate --env=testing

Database Operations

Migrations

# Create migration
php artisan make:migration create_table_name

# Run pending migrations
php artisan migrate

# Rollback last batch
php artisan migrate:rollback

# Fresh migration (⚠️ drops all tables)
php artisan migrate:fresh --seed

Seeders

# Create seeder
php artisan make:seeder TableNameSeeder

# Run all seeders
php artisan db:seed

# Run specific seeder
php artisan db:seed --class=TableNameSeeder

Masked Database Dumps

For development with production data:

# Pull masked dump
php artisan app:pull-masked-dump

# Apply dump
php artisan app:save-masked-dump

Key Development Areas

Backend (PHP)

Creating Controllers:

php artisan make:controller FeatureController

Creating Models:

php artisan make:model ModelName -mfsr
# -m: migration, -f: factory, -s: seeder, -r: resource controller

Creating Form Requests:

php artisan make:request StoreFeatureRequest

Frontend (Vue 3 + TypeScript)

Component Structure:

resources/ts/
├── Components/      # Reusable components
├── Pages/           # Inertia pages (auto-routing)
├── Composables/     # Shared logic
└── Types/           # TypeScript types

Inertia Page Example:

<script setup lang="ts">
import { Head } from '@inertiajs/vue3'

defineProps<{
  data: SomeType
}>()
</script>

<template>
  <Head title="Page Title" />
  <!-- Content -->
</template>

Filament Admin Panels

# Create Filament resource
php artisan make:filament-resource ModelName --generate

# Create Filament page
php artisan make:filament-page PageName

# Create Filament widget
php artisan make:filament-widget WidgetName

Debugging

Tools Available

Laravel Telescope - Request monitoring (dev only)
Laravel Debugbar - Query/performance profiling
Laravel Horizon - Queue monitoring
Laravel Pulse - Production monitoring

Common Debugging Commands

# View logs
tail -f storage/logs/laravel.log

# Tinker (REPL)
php artisan tinker

# Route list
php artisan route:list

# Clear all caches
php artisan optimize:clear

Deployment

Build Process

# Production build
npm run production

# Optimize Laravel
php artisan optimize
php artisan filament:optimize

CI/CD

GitHub Actions workflows: - .github/workflows/laravel.yml - Main CI - .github/workflows/dusk.yml - Browser tests

Environment-Specific

Local: Valet/Homestead with .env
Staging: Pre-production testing
Production: Full monitoring with Pulse/Nightwatch

Architecture Patterns

Multi-Tenancy

Uses Spatie Laravel Multitenancy: - Tenant identification via subdomain/domain - Database-level isolation - Organization-scoped routes

Authentication

Multiple auth strategies: - Firebase Authentication - Passwordless Email - Password + Reset - Google SSO

API Design

SPA APIs (Sanctum authenticated)
Public APIs (iCal feeds)
Admin APIs (web session)

Queue Processing

Laravel Horizon manages queues: - Redis-backed - Job batching - Failed job handling

Helpful Resources

Laravel Boost MCP: Search docs with search-docs tool
Existing Docs: docs/ directory (96+ files)
CLAUDE.md: AI assistant guidelines
README.md: Original setup guide

Contacts

Environment Variables: Contact team lead
Firebase Access: Contact team lead
Deployment Issues: DevOps team