Project Scaffolding and Cleanup

Relevant source files

The following files were used as context for generating this wiki page:

• build_tools/scaffold.sh
• README.md
• src/tasks/seed.rs
• pro_admin/dashboard.toml
• src/graphql/query_root.rs
• build_tools/download_frontend.sh

Introduction

Project Scaffolding and Cleanup refers to the automated processes used to initialize the SeaORM Pro environment with demo data and subsequently strip away demo-specific artifacts to prepare the project for custom development. This system allows developers to explore the full capabilities of the admin panel using a pre-configured "AdventureWorks" dataset before transitioning to their own schema.

The workflow involves downloading frontend assets, seeding a database with multi-encoded TSV files, and finally executing a scaffolding script. This script performs "cleanup" by removing demo entities, migration backups, and specific configuration blocks marked with scaffold-specific comments.

Sources: README.md:1-85, build_tools/scaffold.sh:1-20

Setup and Data Seeding

Before cleanup, the project is scaffolded with a robust set of demo data. This is achieved through the seed_data task and asset retrieval scripts.

Asset Retrieval

The project requires a separate step to fetch the admin panel's compiled frontend assets. The download_frontend.sh script automates this by fetching a compressed archive from the SeaQL repository, extracting it into the assets/admin directory, and cleaning up the temporary archive.

Sources: build_tools/download_frontend.sh:4-15

Seed Task Logic

The SeedData task handles database initialization. It supports a refresh:true variable which triggers a full database reset via the Migrator. The seeder processes various entities (Customers, Addresses, Products, etc.) using specific encodings like WINDOWS_1252 and UTF_16LE to handle legacy data formats correctly.

Entity	Data File	Encoding	Delimiter
Customer	Customer.tsv	WINDOWS_1252	Tab (\t)
Product	Product.tsv	WINDOWS_1252	Tab (\t)
ProductModel	ProductModel.tsv	UTF_16LE	Tilde (~)
ProductDescription	ProductDescription.tsv	UTF_16LE	Tab (\t)

Sources: src/tasks/seed.rs:34-75

The following diagram illustrates the data seeding flow:

Cleanup and Scaffolding Script

The scaffold.sh script is the primary tool for transitioning from a demo state to a production-ready state. It uses a combination of filesystem operations and sed regex replacements to remove boilerplate.

Target Areas for Cleanup

The script targets four main areas of the codebase:

1. Migrations: It replaces the active migration/src with a clean version from migration/bak and strips out specific "SeaORM Pro Plus" marker comments.
2. Models: It preserves only the user.rs model, deleting all other demo-related entity files in src/models/.
3. Configurations: It removes the "Scaffold" blocks from dashboard.toml and deletes all TOML files within pro_admin/raw_tables/ and pro_admin/composite_tables/.
4. Tests: It removes all files within the tests/ directory to ensure no demo tests interfere with new development.

Sources: build_tools/scaffold.sh:4-20

Scaffold Markers

Code sections intended for removal are wrapped in specific comments that the cleanup script targets.

// Start: Scaffold //
// ... (code to be removed) ...
// End: Scaffold //

In TOML files, the script looks for:

# Start: Scaffold
...
# End: Scaffold

Sources: src/tasks/seed.rs:52-78, pro_admin/dashboard.toml:35-95, build_tools/scaffold.sh:11-18

Read-only Mode and Demo Restrictions

The scaffolding includes a mechanism to enforce a read-only state, typically used for public demo sites. This is controlled via the DEMO_SITE environment variable and a GraphQL extension.

Readonly Extension Flow

The ReadonlyExtension intercepts GraphQL requests. If the DEMO_SITE variable is true, it inspects the operation type. If the operation is a Mutation, it returns a ServerError preventing any data modification.

Summary

The project scaffolding and cleanup system provides a lifecycle for the SeaORM Pro admin panel. It begins with the automated retrieval of assets and multi-encoded demo data to provide a functional starting point. Once exploration is complete, the scaffold.sh utility performs a destructive cleanup of demo entities, configurations, and migration files, leaving a clean environment that preserves only the core user management and authentication structures required for new development.

Sources: README.md:68-85, build_tools/scaffold.sh:1-20