# Task D.7 – Initial System Setup Wizard & Seed Framework ## Objective Design and implement a production-ready initialization framework for ALLA OS that allows a brand-new installation to be configured without writing code. The implementation must audit the current project, discover all required seed dependencies, generate reusable CSV templates, provide a generic CSV import engine, and build a Setup Wizard for initializing the system from an empty database. The solution must preserve existing architecture, Organization isolation, Branch scope, Product Type scope, RBAC, Approval Workflow, Document Sequence, Storage, and PDF configuration. --- # Phase 1 — Existing System Audit (Mandatory) Before implementing, perform a complete audit of the current project. Review at minimum: - AGENTS.md - docs/standards/* - docs/adr/* - drizzle/* - src/db/schema.ts - src/db/seeds/**/* - src/features/foundation/**/* - src/features/auth/**/* - src/features/crm/**/* - src/features/approval/**/* - src/features/storage/**/* - src/features/document-sequence/**/* - src/features/master-options/**/* - src/features/pdf/**/* - src/features/organizations/**/* Do not create duplicate seed logic. Reuse existing services whenever possible. --- # Phase 2 — Seed Dependency Analysis Audit every table and identify: - Required - Optional - Generated - Runtime only Generate a dependency graph. Example Organization → Branch → Membership → User → Customer → Contact → Lead → Opportunity → Quotation → Approval Produce a report containing: - Seed order - Dependency tree - Circular dependency detection - Missing seed data - Existing seed coverage - Recommended improvements No implementation should begin until this report is complete. --- # Phase 3 — Seed Classification Separate all seed data into four groups. ## Foundation Seed Required for every installation. Examples - System Configuration - Roles - Permissions - Master Option Categories - Master Options - Status Definitions - Document Types - Product Types - Currency - Tax Rates - Storage Providers - Notification Types - Approval Types - Default PDF Templates --- ## Organization Seed Organization-specific data. Examples - Organization - Company Profile - Branch - Department - Team - Warehouse - Position - Company Logo - Signature - Email Settings - Approval Matrix - Document Sequence --- ## Business Seed Operational data. Examples - Customer - Contact - Site - Product - Service - Price Book - Lead - Opportunity - Quotation - Quotation Items --- ## Demo / UAT Seed Sample business data. Create realistic demo data for: Organization - ALLA - ONVALLA Users - IT - Marketing - Sales - Sales Manager - CEO Customers Leads Opportunities Approved Quotations Rejected Quotations Follow-up Activities Attachments --- # Phase 4 — CSV Template Generator Generate reusable CSV templates for every importable entity. Directory /setup/templates/ Example organizations.csv branches.csv users.csv memberships.csv roles.csv permissions.csv customers.csv contacts.csv sites.csv products.csv leads.csv opportunities.csv quotations.csv quotation-items.csv approval-matrix.csv document-sequences.csv master-options.csv currencies.csv tax-rates.csv Each template must contain - Header - Sample row - Required fields - Optional fields - Enum examples - Validation rules - Relationship examples --- # Phase 5 — Generic CSV Import Engine Create a reusable import engine. Requirements - CSV Parser - Validation - Required field checking - Enum validation - Foreign key resolution - Duplicate detection - Upsert support - Transaction support - Rollback on failure - Import report Return - Imported - Updated - Skipped - Errors - Warnings The engine must be reusable by every future module. --- # Phase 6 — Setup Wizard Create a new Administration page. Administration └── Setup Wizard Wizard flow ## Step 1 System Readiness Check - Environment Variables - Database - Storage - Migration Status - Upload Directory - PDF Template - Email Configuration --- ## Step 2 Initialize Foundation Install - Foundation Seed - Roles - Permissions - Master Data --- ## Step 3 Organization Setup Configure - Company Name - Organization Code - Tax ID - Address - Logo - Default Currency - Fiscal Year --- ## Step 4 Branch Setup Configure - Branch - Department - Team - Warehouse --- ## Step 5 CSV Import Upload CSV files. Preview - Data - Validation - Error Summary Support partial import. --- ## Step 6 Document Sequence Configure Organization ↓ Branch ↓ Product Type ↓ Prefix ↓ Running Number Preview CRA2607-001 DKA2607-001 SCO2607-001 --- ## Step 7 Approval Workflow Configure - Sequential - Any One - Amount-based Approval Preview approval flow. --- ## Step 8 Administrator Create first administrator account. Assign - System Admin - Organization Admin --- ## Step 9 Verification Automatically verify - Login - Permission - Organization - Branch - Document Sequence - Approval - Storage - PDF - Email Display PASS WARNING FAIL --- ## Step 10 Finish Generate - Setup Summary - Seed Summary - Import Summary - Verification Report --- # Phase 7 — Reset & Reseed Create reusable reset commands. Support - Reset Foundation - Reset Organization - Reset Demo Data - Reset Business Data - Full Reset All operations must be transactional. --- # UI Requirements Use shadcn/ui. Implement - Stepper Wizard - Progress Bar - Import Preview Table - Validation Badge - Summary Cards - Success Screen - Error Screen - Resume Setup - Dark Mode - Responsive Layout --- # Technical Requirements - Reuse existing services. - Do not duplicate business logic. - Idempotent seed operations. - Organization-aware. - Branch-aware. - Product Type-aware. - Transaction-safe. - Extensible for future modules. - Follow ALLA OS coding standards. --- # Deliverables - Seed dependency audit report - Seed inventory matrix - CSV templates - Generic CSV import engine - Setup Wizard - Validation engine - Verification engine - Reset engine - Seed execution report - Technical documentation --- # Acceptance Criteria > Implementation log 2026-07-02: Phase 1/2 audit completed and saved to > `docs/implementation/task-d7-initial-system-setup-audit.md`. Implementation > is intentionally gated until this seed dependency audit report is reviewed. - Empty database can be initialized entirely through the Setup Wizard. - All Foundation data can be installed without manual SQL. - Organizations can be created from the wizard. - CSV templates cover every importable master and business entity. - CSV imports support validation, preview, rollback, and upsert. - Demo/UAT data can be generated independently from Foundation data. - System verification reports all required services before first login. - Reset and reseed operations are repeatable and deterministic. - Existing functionality remains backward compatible.