6.9 KiB
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
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.