Dev chart seeding

Dev/E2E Chart of Accounts Seeding

This system provides convenient ways to seed development and testing organizations with a standard set of chart of accounts, eliminating the need to manually create accounts during testing.

Overview

The seeding system provides the following standard dev chart of accounts:

Account Name	Number	Type	Description	Reconciled
Shopify Bank	1200	Credit	Shopify bank account	❌
Paypal Bank	1201	Credit	PayPal bank account	❌
Paypal Working Capital	1300	Credit	PayPal working capital	❌
Shopify Deb.	70000	Debit	Shopify debtor account	✅
Paypal Deb	70001	Debit	PayPal debtor account	✅
Shopify Fee	4970	Debit	Shopify fees	❌
Paypal Fee	4971	Debit	PayPal fees	❌
Shopify Transit	1360	Credit	Shopify transit account	❌
Paypal Transit	1361	Credit	PayPal transit account	❌
Währungsdifferenzen	2150	Debit	Currency differences	❌
Rev DE	8000	Debit	Revenue Germany	❌
Rev AT	8001	Debit	Revenue Austria	❌
Rev CH	8002	Debit	Revenue Switzerland	❌
Rev FR	8003	Debit	Revenue France	❌
Rev UK	8004	Debit	Revenue United Kingdom	❌
Rev ES	8005	Debit	Revenue Spain	❌
other deb	80000	Debit	Other debtor accounts	❌
fallback	99999	Debit	Fallback account	❌

Usage Methods

1. UI Button (Recommended for Manual Testing)

Navigate to /setup/chart-of-accounts in your dev environment and click the “🛠️ Seed Dev Accounts” button in the chart of accounts card header.

• Only visible in development environment (NODE_ENV === “development”)
• Uses the new warning button variant with proper CI colors for dev/testing purposes
• Shows loading state during seeding
• Displays success/error toasts
• Automatically refreshes the page to show new accounts

2. CLI Script (Recommended for Automation)

Use the CLI script for automated testing or CI/CD pipelines:

# Interactive mode (will prompt for required parameters)
pnpm seed:dev-chart

# Non-interactive mode with parameters
pnpm seed:dev-chart <organizationId> [actorId]

# Direct script usage
node scripts/seed-dev-chart-accounts.mjs [organizationId] [actorId]

Examples:

Interactive Mode:

# Will prompt for organization ID and optionally actor ID
pnpm seed:dev-chart

# Example interactive session:
🌱 Dev Chart of Accounts Seeding Tool

📋 Enter Organization ID (required): cloze123abc456def789
👤 Enter Actor ID (optional): [press enter to auto-detect]

🏢 Organization ID: cloze123abc456def789
👤 Actor ID: Auto-detect
✅ Proceed with seeding? This will create/update 18 chart accounts (y/N): y

Non-Interactive Mode:

# Seed organization with ID (auto-finds actor)
pnpm seed:dev-chart cloze123abc456def789

# Seed with specific actor for audit trail
pnpm seed:dev-chart cloze123abc456def789 actor456def789

Environment Requirements:

• DATABASE_URL must be set (uses organization’s database)

Features

• Interactive Prompts: Asks for required parameters if not provided as arguments
• Validation: Validates organization ID format
• Confirmation: Shows summary and asks for confirmation before seeding
• Non-Interactive Mode: Supports automation by providing arguments

3. Server Action (Programmatic Use)

For programmatic usage in tests or other server-side code:

import { seedDevChartOfAccounts } from "@/app/lib/actions/chart_of_accounts/seed-dev-chart-of-accounts";

// Within an authenticated context (requires auth)
const result = await seedDevChartOfAccounts();
if (result.success) {
  console.log(`Seeded ${result.data.length} accounts`);
}

E2E Testing Integration

Playwright/E2E Tests

Add this to your test setup:

// In your test setup or beforeEach
await page.goto("/setup/chart-of-accounts");
await page.click('button:has-text("🛠️ Seed Dev Accounts")');
await page.waitForSelector('.sonner-toast:has-text("Seeded")');

CI/CD Integration

Add to your CI pipeline after creating a test organization:

- name: Seed dev chart of accounts
  run: |
    export DATABASE_URL=${{ secrets.TEST_DATABASE_URL }}
    # Non-interactive mode for CI
    pnpm seed:dev-chart ${{ env.TEST_ORG_ID }}

Note: In CI/CD environments, always provide parameters as arguments to avoid interactive prompts.

Features

• Upsert Logic: Accounts are upserted, so running the seed multiple times is safe
• Existing Account Handling: Won’t duplicate accounts, will update existing ones
• Audit Trail: Uses actor ID for created/modified by tracking
• Error Handling: Continues seeding even if individual accounts fail
• Logging: Comprehensive logging for debugging
• Single Source of Truth: Chart data defined once in CLI script, imported by UI seeding functions

Important Notes

⚠️ This is for development/testing only!

• This seeding is NOT part of production organization setup
• It’s separate from the standard organization seeding in create-organisation.ts
• The UI button only appears in development environment and uses the proper warning variant styling
• Accounts are created with standard test data, not production-ready configurations
• Uses centralized getEnvironmentInfo() utility for consistent dev environment detection

Modifying Chart Data

To add, remove, or modify the standard dev chart of accounts:

1. Edit only apps/webapp/scripts/seed-dev-chart-accounts.mjs
2. Update the DEV_CHART_OF_ACCOUNTS array
3. Both UI button and CLI will automatically use the updated data

The chart data is defined once in the CLI script and imported by the UI seeding functions, ensuring consistency and eliminating duplication.

File Structure

apps/webapp/
├── scripts/
│   └── seed-dev-chart-accounts.mjs        # 📋 CLI script + single source of truth for chart data
├── app/lib/actions/chart_of_accounts/
│   ├── chart-of-accounts-seed.ts          # Core seeding logic (imports from CLI script)
│   └── seed-dev-chart-of-accounts.ts      # Server action wrapper
├── app/lib/utils/
│   └── environment.ts                     # Centralized environment utilities (existing)
├── app/ui/cards/
│   └── chart-of-accounts-settings-card.tsx # UI with dev-only seed button
└── ../../internal-docs/dev-chart-seeding.mdx # This documentation

Troubleshooting

“Organization not found” error:

• Verify the organization ID is correct
• Ensure you have database access

“Actor not found” warning:

• The script will continue without an actor ID
• You can provide a specific actor ID as the second parameter

Database connection errors:

• Verify DATABASE_URL environment variable is set
• Check database connectivity

UI button not visible:

• Ensure you’re in a development environment
• Check that you’re authenticated and have access to the organization

Environment Utilities Usage

You can use the existing environment utilities in other components for consistent environment detection:

import { getEnvironmentInfo } from "@/app/lib/utils/environment";

// Get full environment info
const { isDev, isStaging, isProduction, envType } = getEnvironmentInfo();

// Conditional logic for dev-only features
if (isDev) {
  // Dev-only code
}

// Or for dev AND staging features
if (isDev || isStaging) {
  // Dev and staging code
}