Spark Lab

Spark Lab is a Laravel 13 application for tracking an idea from initial framing to implementation outcome. The core workflow is server-rendered Blade UI over Eloquent models, with lightweight Alpine for theme and typography preferences.

Project Overview

The platform is organized around a single primary record, the Spark, with ordered execution notes, references, tags, and a recorded outcome.

• Capture an idea with title, summary, details, visibility, and tags.
• Break the work into ordered Steps.
• Attach Resources to steps as URL bookmarks with optional notes.
• Record an Outcome when the work is complete.
• Browse shared Sparks through a public explore surface.

Core Concepts

• Spark: top-level idea or work item. Stores title, summary, details, visibility, completion state, owner, and view count.
• Step: ordered action under a Spark. Each step belongs to one Spark and has a numeric position.
• Outcome: final solution summary stored on the Spark itself. Saving an outcome marks the Spark completed.
• Tag: normalized lowercase labels used for discovery, filtering, and related Spark suggestions.
• Resource: a step-level bookmark (step_bookmarks table) with title, url, and optional note.

Architecture

• Backend: Laravel 13, PHP 8.3, Eloquent ORM, Blade views.
• Frontend: Blade + Tailwind CSS v4 + Alpine.js + Vite.
• Data layer:
  • sparks
  • steps
  • tags
  • spark_tag
  • step_bookmarks
  • framework tables for users, cache, jobs, and database-backed sessions/queues
• Auth: session-based auth with email-first registration and signed verification links.
• Search/filtering: SQL LIKE search on Spark title/summary plus tag filtering.
• Analytics: per-Spark view_count.

Features

• Spark CRUD for authenticated users
• Ordered Step creation on the Spark detail page
• Step Resources/bookmarks with URL validation
• Outcome tracking and automatic completion timestamping
• Tag normalization, deduplication, sync, and filtering
• Related Spark suggestions based on shared tags
• Shared/explore listing for Sparks with shared visibility
• Search by title and summary
• Simple usage analytics via view counts
• Seeded realistic starter dataset
• SEO metadata for landing, Spark list/detail, and auth pages
• Theme system with light, dim, and dark
• Typography modes with serif, sans, and mono

Local Setup

Requirements

• WSL2 or Linux shell environment
• PHP 8.3 with common Laravel extensions
  • bcmath, ctype, curl, dom, fileinfo, mbstring, openssl, pdo, pdo_mysql, sqlite3, tokenizer, xml
• Composer
• Node.js 20+ and npm
• MariaDB 10.6+ or SQLite

Install

composer install
cp .env.example .env
php artisan key:generate
npm install

Database

Default .env.example uses SQLite. For local MariaDB, update .env:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=spark_lab
DB_USERNAME=spark_lab
DB_PASSWORD=secret

Create the database, then run:

php artisan migrate
php artisan db:seed

If you prefer SQLite:

touch database/database.sqlite
php artisan migrate
php artisan db:seed

Frontend Assets

npm run dev

For production-style assets:

npm run build

Run the App

In separate terminals:

php artisan serve
npm run dev

Or use the Composer convenience script:

composer run dev

Environment Configuration

Key .env values:

• APP_URL: base URL used in signed links and metadata
• DB_*: MariaDB or SQLite configuration
• MAIL_*: required for registration and password reset emails outside local log mailer mode
• QUEUE_CONNECTION=database: used by default
• SESSION_DRIVER=database: database-backed sessions
• CACHE_STORE=database: database-backed cache

For local email inspection, leave MAIL_MAILER=log or point Mailpit/Mailhog settings into .env.

Development Workflow

Typical loop:

php artisan migrate
php artisan db:seed
php artisan serve
npm run dev

Useful commands:

php artisan test
php artisan pail
php artisan queue:listen --tries=1 --timeout=0
./vendor/bin/pint

Testing

Run the full suite:

php artisan test

The test suite covers:

• auth and signed-link flows
• Spark CRUD
• shared/explore visibility behavior
• steps, resources, tags, search, and outcome handling
• seed data generation
• SEO and navigation behavior

Use a dedicated test database if switching from SQLite to MariaDB locally.

Theme System

UI preferences are persisted in localStorage and applied through root data attributes.

• Theme modes: light, dim, dark
• Typography modes: serif, sans, mono
• Theme storage key: spark-theme
• Font storage key: spark-font

Implementation points:

• token definitions in resources/css/app.css
• Alpine preference controller in resources/js/app.js

Auth Flow

Registration is email-first.

1. User submits email on the registration request form.
2. App sends a temporary signed verification link.
3. Visiting the link stores the verified email in session.
4. Registration completion form is only accessible with that verified session state.
5. User sets name and password, account is created with email_verified_at, and the session is authenticated.

Password reset follows the same signed-link pattern:

1. request reset by email
2. receive temporary signed link
3. verified email is stored in session
4. password is reset from the guarded form

Relevant controllers:

• app/Http/Controllers/RegistrationLinkController.php
• app/Http/Controllers/AuthenticatedSessionController.php
• app/Http/Controllers/PasswordResetLinkController.php
• app/Http/Controllers/PasswordResetController.php

Deployment

Build

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

Runtime Checklist

• set APP_ENV=production
• set APP_DEBUG=false
• set correct APP_URL
• configure real MAIL_* settings
• ensure database credentials are production-safe
• run a queue worker if mail/jobs are moved off sync/log handling
• expose public/ through the web server
• make storage/ and bootstrap/cache/ writable

Web Server Notes

• Nginx/Apache document root should point to public/
• serve built Vite assets from public/build
• terminate HTTPS before the app or configure trusted proxies correctly

Repository Notes

• The app is server-rendered first; Alpine is used only for small interactive controls.
• Shared visibility is implemented with the stored value visibility = public, even where UI labels say Shared.
• Seed data can be regenerated with:

php artisan db:seed