libra/docs/stories/story-1.1-project-setup-database-schema.md

Story 1.1: Project Setup & Database Schema

Epic Reference

Epic 1: Core Foundation & Infrastructure

User Story

As a developer, I want the Laravel 12 project configured with all required packages and complete database schema, So that the foundation is established for all subsequent feature development.

Story Context

Existing System Integration

• Integrates with: New project setup (greenfield)
• Technology: Laravel 12, PHP 8.4, Livewire 3, Volt, Flux UI Free, Tailwind CSS 4
• Follows pattern: Laravel 12 streamlined file structure
• Touch points: Database migrations, model factories, development environment

Acceptance Criteria

Functional Requirements

• Laravel 12 project created with Livewire 3, Volt, Flux UI
• Tailwind CSS 4 configured with @theme directive
• Database migrations for all core tables:
  • users (with user_type, national_id, company fields)
  • consultations
  • timelines
  • timeline_updates
  • posts
  • working_hours
  • blocked_times
  • notifications
  • admin_logs
• Model factories created for testing
• Development environment working (composer run dev)

Integration Requirements

• SQLite configured for development database
• All migrations run without errors
• Factories generate valid test data
• Composer and npm scripts functional

Quality Requirements

• All database tables have proper indexes
• Foreign key constraints properly defined
• Factories cover all required fields
• Development server starts without errors

Technical Notes

• Database: Use SQLite for development (configurable for MariaDB in production)
• Environment: Set DB_CONNECTION=sqlite in .env for development
• Reference: PRD Section 16.1 for complete schema details
• Pattern: Follow existing Volt class-based component pattern
• Structure: Use Laravel 12 streamlined file structure (no app/Http/Middleware, bootstrap/app.php for config)
• Testing: Use Pest 4 for all tests (php artisan make:test --pest)
• Models: Create with php artisan make:model ModelName -mf (migration + factory)
• Notifications table: Custom implementation per PRD schema (not Laravel's built-in notifications)

Database Schema Reference

users:
  - id, name, email, password, user_type (enum: admin/individual/company)
  - national_id (nullable), company_name (nullable), company_registration (nullable)
  - phone, preferred_language (enum: ar/en), status (enum: active/deactivated)
  - timestamps, email_verified_at

consultations:
  - id, user_id, scheduled_date, scheduled_time, duration (default 45)
  - status (enum: pending/approved/completed/cancelled/no_show)
  - type (enum: free/paid), payment_amount (nullable), payment_status
  - problem_summary, admin_notes, timestamps

timelines:
  - id, user_id, case_name, case_reference (unique nullable)
  - status (enum: active/archived), timestamps

timeline_updates:
  - id, timeline_id, admin_id, update_text, timestamps

posts:
  - id, title_ar, title_en, body_ar, body_en
  - status (enum: draft/published), timestamps

working_hours:
  - id, day_of_week (0-6), start_time, end_time, is_active, timestamps

blocked_times:
  - id, block_date, start_time (nullable), end_time (nullable)
  - reason, timestamps

admin_logs:
  - id, admin_id, action_type, target_type, target_id
  - old_values (json), new_values (json), ip_address, timestamps

Definition of Done

• All database migrations created and tested
• All model factories functional
• Development environment runs with composer run dev
• Tests pass for model creation using factories
• Code formatted with Pint
• No errors on fresh install

Test Scenarios

All tests should use Pest 4 (php artisan make:test --pest).

Migration Tests

• All migrations run successfully: php artisan migrate:fresh
• Migrations can rollback without errors: php artisan migrate:rollback
• Foreign key constraints are properly created (timeline_updates.timeline_id, timeline_updates.admin_id, consultations.user_id, timelines.user_id, admin_logs.admin_id)

Factory Tests

• UserFactory creates valid User with all user_type enum values (admin, individual, company)
• ConsultationFactory creates valid Consultation with proper user relationship
• TimelineFactory creates valid Timeline with proper user relationship
• TimelineUpdateFactory creates valid TimelineUpdate with timeline and admin relationships
• PostFactory creates valid Post with bilingual fields
• WorkingHoursFactory creates valid WorkingHours for each day_of_week (0-6)
• BlockedTimeFactory creates valid BlockedTime entries
• NotificationFactory creates valid Notification entries
• AdminLogFactory creates valid AdminLog with JSON fields

Enum Validation Tests

• User.user_type only accepts: admin, individual, company
• User.status only accepts: active, deactivated
• User.preferred_language only accepts: ar, en
• Consultation.status only accepts: pending, approved, completed, cancelled, no_show
• Consultation.type only accepts: free, paid
• Timeline.status only accepts: active, archived
• Post.status only accepts: draft, published

Edge Case Tests

• Nullable fields accept null values (national_id, company_name, case_reference, etc.)
• JSON fields (old_values, new_values) store and retrieve correctly
• Unique constraint on case_reference allows multiple nulls but no duplicate values

Dependencies

• None (this is the foundation story)

Risk Assessment

• Primary Risk: Schema design changes required later
• Mitigation: Follow PRD specifications closely, validate with stakeholder
• Rollback: Fresh migration reset possible in development

Error Handling

• Migration failures: Run php artisan migrate:status to identify failed migrations, fix the issue, then php artisan migrate to continue
• Foreign key errors: Ensure referenced tables are created before dependent tables (migrations run in filename order)
• Factory errors: Ensure factories define all required (non-nullable) fields and use valid enum values

Estimation

Complexity: Medium Estimated Effort: 4-6 hours