# LeadPilot — Migration Execution Sequence & Migration Architecture

**Document Version:** 1.0.0 (Phase 5 Database Architecture Lock)  
**Status:** Approved & Formally Enforced for Phase 6 Implementation  

---

## 1. Migration Execution Sequence (16 Ordered Migrations)

All database migrations must execute in strict dependency order:

```
+---------------------------------------------------------------------------------------------------------------+
| ORDER | MIGRATION FILENAME BLUEPRINT                                | PRIMARY TABLES CREATED                  |
+-------+-------------------------------------------------------------+-----------------------------------------+
| 001   | `2026_08_30_000001_create_users_table.php`                  | `users`                                 |
| 002   | `2026_08_30_000002_create_workspaces_table.php`             | `workspaces`                            |
| 003   | `2026_08_30_000003_create_workspace_members_table.php`      | `workspace_members`                     |
| 004   | `2026_08_30_000004_create_pipelines_and_stages_table.php`  | `pipelines`, `pipeline_stages`          |
| 005   | `2026_08_30_000005_create_lead_sources_table.php`           | `lead_sources`                          |
| 006   | `2026_08_30_000006_create_leads_table.php`                  | `leads`                                 |
| 007   | `2026_08_30_000007_create_lead_activities_table.php`        | `lead_activities`                       |
| 008   | `2026_08_30_000008_create_lead_notes_table.php`             | `lead_notes`                            |
| 009   | `2026_08_30_000009_create_tags_and_lead_tags_table.php`     | `tags`, `lead_tags`                     |
| 010   | `2026_08_30_000010_create_message_templates_table.php`      | `message_templates`                     |
| 011   | `2026_08_30_000011_create_follow_up_sequences_table.php`    | `follow_up_sequences`, `...steps`       |
| 012   | `2026_08_30_000012_create_follow_ups_table.php`             | `follow_ups`                            |
| 013   | `2026_08_30_000013_create_ai_intelligence_tables.php`       | `ai_scores`, `ai_usage_logs`            |
| 014   | `2026_08_30_000014_create_webhook_and_import_tables.php`    | `webhook_sources`, `...logs`, `imports` |
| 015   | `2026_08_30_000015_create_security_and_settings_tables.php` | `api_keys`, `settings`, `audit_logs`    |
| 016   | `2026_08_30_000016_create_system_infrastructure_tables.php` | `notifications`, `licenses`, `jobs`     |
+---------------------------------------------------------------------------------------------------------------+
```

---

## 2. Safe Migration Invariants

1. **Zero Raw Drop Columns:** Production upgrades must never run destructive `DROP COLUMN` commands without a preceding deprecation cycle.
2. **Deterministic Down Methods:** Every migration MUST implement a functional `down()` method reversing table/column additions cleanly for testing rollback support.