Quick Start

Prerequisites

• PHP 8.3+ with extensions: pdo_pgsql, mbstring, openssl, tokenizer, xml
• Node.js 20+ and npm
• PostgreSQL (production uses Supabase-hosted Postgres)
• Composer 2.x

Local development setup

1. Clone and install

git clone [email protected]:The-Hidden-Door-LLC/miranda.git
cd miranda/code/miranda.foundation

composer install
npm install

2. Configure environment

cp .env.example .env
php artisan key:generate

Edit .env with your local database credentials and service keys:

# Database (PostgreSQL)
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=miranda
DB_USERNAME=your_user
DB_PASSWORD=your_password

# Supabase Auth
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_JWT_SECRET=your-jwt-secret
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Stripe (test keys)
STRIPE_KEY=pk_test_...
STRIPE_SECRET=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Resend (email)
RESEND_KEY=re_...

# Twilio (SMS)
TWILIO_SID=AC...
TWILIO_TOKEN=...
TWILIO_FROM=+1...

3. Run migrations

php artisan migrate

4. Start the dev server

The project includes a composer dev script that starts all services concurrently:

composer dev

This launches four processes in parallel:

Process	Command	Purpose
Server	php artisan serve	API and web routes
Queue	php artisan queue:listen	Background jobs (campaigns, imports, sequences)
Logs	php artisan pail	Real-time log tailing
Vite	npm run dev	Vue SPA hot-reload

The admin SPA is available at http://localhost:8000/app.

Project structure

miranda.foundation/
├── app/
│   ├── Concerns/          # Shared traits (HasUuid)
│   ├── Enums/             # PHP 8.1 backed enums
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── Api/       # Foundation-authenticated endpoints
│   │   │   │   └── Donor/ # Donor-authenticated endpoints
│   │   │   └── Public/    # Unauthenticated endpoints (webhooks, donate, scholarships)
│   │   └── Middleware/     # Auth, foundation context, role checks
│   ├── Jobs/              # Queued jobs (SendCampaignBatch, ImportContactsBatch, etc.)
│   ├── Mail/              # Mailable classes (DonationReceiptMail, TeamInviteMail)
│   ├── Models/            # Eloquent models (UUID primary keys)
│   └── Services/          # Business logic layer
├── config/
│   ├── permissions.php    # Permission key registry
│   ├── plans.php          # Plan tiers, limits, and features
│   └── org-types.php      # Organization type definitions and default roles
├── database/migrations/   # Schema migrations (idempotent)
├── resources/js/          # Vue 3 SPA source
├── routes/
│   ├── api.php            # API route definitions
│   └── web.php            # Web routes (SPA catch-all, webhooks, public pages)
└── tests/                 # Pest PHP tests

First steps after setup

1. Register a foundation — Authenticate via Supabase, then POST /api/register with foundation_name and optional org_type
2. Configure Stripe Connect — POST /api/stripe/onboard to start Express account onboarding
3. Import contacts — Upload a CSV via POST /api/import/upload, map columns, then POST /api/import/confirm
4. Create a donation page — POST /api/donation-pages with title, type, and suggested amounts
5. Send a test campaign — Create a campaign with segment criteria, then POST /api/campaigns/{id}/send

Running tests

composer test

Tests use Pest PHP with the Laravel plugin.

Key dependencies

Package	Purpose
laravel/framework ^13.0	Laravel 12 framework
laravel/cashier ^16.5	Subscription billing
stripe/stripe-php ^17.6	Stripe API client
firebase/php-jwt ^7.0	JWT decode for Supabase tokens
resend/resend-laravel ^1.3	Transactional email
twilio/sdk ^8.11	SMS messaging
vue ^3.5	Frontend framework
primevue ^4.5	UI component library
pinia ^3.0	Vue state management
@supabase/supabase-js ^2.99	Auth client