# 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.
