SPACEPORT DOCS

Scaffolding

In Spaceport, a "scaffold" refers to the organizational structure of your project—the arrangement of assets, source code modules, templates, and all other directories and files that constitute your application. While Spaceport is engineered for maximum flexibility, we recommend certain structural patterns depending on your project's type and complexity. This organized approach streamlines development, support, and maintenance.

# What Defines a Scaffold?

A Spaceport scaffold can range from a single file for very simple applications to a complex, multi-directory structure for sophisticated projects. The precise layout and composition of your scaffold are primarily defined within the Spaceport Manifest Configuration File (config.spaceport). This file tells Spaceport where to find various components of your application. However, Spaceport also supports manifest-free operation for ultimate simplicity and quick prototyping.

This guide explores four main approaches to scaffolding:

# Choosing Your Scaffold Strategy

Different projects call for different scaffolding approaches:

Use --no-manifest when:

Use Port-Echo when:

Use Port-Mercury when:

Use CLI generation when:

# The Minimalist Approach: --no-manifest

For rapid prototyping or straightforward tasks, you can run Spaceport with minimal setup using the --no-manifest argument. In this mode, Spaceport operates with as little as a single Groovy source module folder containing the code that Spaceport's Source Loader will execute.

Example: A Single-File Application

+ [SPACEPORT_ROOT]/
  - spaceport.jar
  + modules/
    - App.groovy

In this setup:

Starting the Application:

java -jar spaceport.jar --start --no-manifest

When launched, Spaceport's Source Loader automatically discovers Groovy files inside the modules/ folder and starts with a default configuration. This is excellent for quickly launching a simple application or script.

Limitations:

The default configuration only loads source modules in the top level of the modules/ directory. Subdirectories are ignored. For projects that need: - Subdirectory organization (package-like structure) - Database migrations - Static asset management - Launchpad templating - Custom configuration

You'll benefit from a more structured scaffold with a manifest file.

# Starter Kit Scaffolds

To help you get started quickly with structured projects, Spaceport offers two starter kits with pre-configured scaffolds tailored to different application needs.

## Port-Echo: The Minimalist Starter Kit

Port Echo Starter Kit

The Port-Echo Starter Kit offers a foundational scaffold, perfect for developers who want to begin with a clean slate and incrementally opt into Spaceport features. It's an ideal choice if you have a clear vision for your application's architecture and prefer to build from the ground up.

Structure:

+ [SPACEPORT_ROOT]/
  - spaceport.jar
  - config.spaceport
  + modules/
    - Echo.groovy

What's Included:

Port-Echo is perfect for experienced developers who understand their requirements and want to build their structure organically as the application grows.

Get Started: Download Port-Echo from the Port-Echo GitHub repository. For detailed instructions, see the Developer Onboarding Guide.

## Port-Mercury: A Full-Featured Starter Kit

Port Mercury Starter Kit

The Port-Mercury Starter Kit provides a comprehensive scaffold designed for building robust, single-tenant Spaceport applications. It comes pre-configured with several key Spaceport features and demonstrates a more structured approach to application development.

Structure:

+ [SPACEPORT_ROOT]/
  - spaceport.jar
  - config.spaceport
  + modules/        
    - App.groovy    
    - Router.groovy 
  + assets/         
    + img/
      - error.png
      - icon.svg
      - spacegal.svg
  + launchpad/      
    + elements/     
    + parts/        
      - wrapper.ghtml
      - index.ghtml
      + pages/        
        - contact.ghtml
      + admin/
        - login.ghtml
        - overview.ghtml
      + error-pages/
        - 4XX.ghtml
        - 5XX.ghtml
  + migrations/    
    - CreateSpaceportAdministrator.groovy

What's Included:

Port-Mercury is an excellent choice for developers looking to quickly bootstrap a feature-rich application and explore real-world Spaceport implementations. It provides working examples of nearly every major Spaceport feature, making it ideal for learning or kickstarting production applications.

Get Started: Download Port-Mercury from the Port-Mercury GitHub repository. For detailed instructions, see the Developer Onboarding Guide.

# CLI-Generated Scaffolds

The Spaceport Command-Line Interface (CLI) includes an interactive command to generate a customized scaffold for your application. The --create-port command creates a directory structure with essential components, guiding you through configuration options to tailor the scaffold to your needs.

Creating a New Project:

java -jar spaceport.jar --create-port

The CLI will prompt you for:

This approach combines the benefits of starter kits with the flexibility of customization during setup, making it ideal for creating multiple projects with similar but not identical structures.

Learn More: Check out the Spaceport CLI Documentation for details on all available CLI commands.

# Anatomy of a Complete Scaffold

Understanding the components of a well-structured scaffold helps you organize your application effectively. Below is a breakdown of the core Spaceport systems and their roles within your project's filesystem.

A Complete Scaffold Structure:

+ [SPACEPORT_ROOT]/
  - spaceport.jar
  - config.spaceport
  + modules/        # Source code
  + assets/         # Static files (CSS, JS, images)
  + launchpad/      # Templates and components
    + elements/     # Reusable server elements
    + parts/        # Page templates
  + migrations/     # Database evolution scripts
  + ignition/       # Pre-launch initialization scripts
  + logs/           # Application logs (created automatically)

Not every application needs all components. Choose what makes sense for your project and configure paths in your manifest file.

## Source Modules: The Heart of Your Application

Source modules are Groovy files (.groovy) that form the core logic of your Spaceport application. When Spaceport starts, the Source Loader identifies and executes these modules, powering your application.

Purpose:

Location:

Configuration:

The Spaceport Manifest file (config.spaceport) lets you enable subdirectory scanning and specify multiple source paths. This allows you to organize code into logical groupings similar to traditional Java/Groovy projects.

Example Structure: 

modules/
  Router.groovy
  App.groovy
  utils/
    StringHelpers.groovy
    DateUtils.groovy
  documents/
    UserDocument.groovy
    ArticleDocument.groovy
  services/
    EmailService.groovy
    PaymentService.groovy

Learn More: The Source Modules Documentation provides a deep dive into module types, best practices, hot-reloading, and advanced patterns. For configuration details, see the Manifest Configuration File.

## Static Assets: Serving Frontend Resources

Static assets are files served directly by Spaceport to the client without server-side processing—images, CSS stylesheets, client-side JavaScript, fonts, and other non-dynamic content.

Purpose:

Location:

Configuration:

The manifest file maps URL paths to filesystem directories. You can configure multiple asset paths with different access patterns:

static assets:
  paths:
    /assets/* : assets/
    /public/* : public/

Precedence:

Static assets are checked before dynamic routes. If a request matches both a static file and a route handler, the static file is served.

Learn More: See the Static Assets Documentation for serving strategies, security considerations, and advanced configurations. For manifest settings, see Manifest Configuration.

## Launchpad: Server-Side Templating and Components

Launchpad is Spaceport's integrated system for server-side HTML templating, reactive updates, and reusable UI components. It's one of Spaceport's most powerful features, enabling you to build dynamic, interactive web applications with minimal client-side JavaScript.

Purpose:

Structure:

A Launchpad-enabled scaffold typically includes:

launchpad/
  elements/          # Reusable components (like React components)
    Button.ghtml
    UserCard.ghtml
    Navigation.ghtml
  parts/             # Page templates
    wrapper.ghtml    # Layout wrapper
    index.ghtml      # Home page
    about.ghtml
    + admin/         # Admin section templates
      dashboard.ghtml

Key Concepts: - Parts: Full page templates that define HTML structure and content - Elements: Reusable components with encapsulated logic and markup - Dock: A reactive data container that automatically updates the UI when values change - Transmissions: Real-time server-to-client communication for interactive updates

Configuration: While Launchpad uses the project root as its default base directory, you can configure a specific path when initializing Launchpad in your source modules.

Learn More: The Launchpad Documentation provides comprehensive guidance on templates, reactive programming, server elements, and interactive patterns. Also see Transmissions for real-time updates and Server Elements for component development.

## Migration Scripts: Managing Application Evolution

Migration scripts are Groovy files executed by the Spaceport Administrator to perform tasks outside the normal request-response cycle. They manage your application's evolution as requirements change over time.

Purpose: - Create and configure databases - Add or modify document structures - Seed initial data or test fixtures - Perform one-time data transformations - Update configuration or system state

Location: - Recommended: migrations/ directory at project root - Configurable: Specify a custom path in the manifest file

Usage: Run migrations through the CLI:

java -jar spaceport.jar --migrate config.spaceport

This launches an interactive menu where you can select which migrations to execute.

Example Migration: 

// CreateSpaceportAdministrator.groovy
import spaceport.Spaceport
import spaceport.computer.memory.physical.Document

def db = Spaceport.main_memory_core

// Ensure the users database exists
if (!db.containsDatabase('users')) {
    db.createDatabase('users')
}

// Create admin user
def admin = Document.get('admin', 'users')
admin.fields.username = 'admin'
admin.fields.email = 'admin@example.com'
admin.fields.role = 'administrator'
admin.save()

println "Administrator created successfully!"

Learn More: The Migrations Documentation includes detailed examples, best practices, and patterns for data evolution. For configuration options, see Manifest Configuration.

## Ignition Scripts: Pre-Launch Preparations

Ignition scripts are Groovy files executed by Spaceport's Ignition system before any source modules are loaded. They perform critical setup tasks that must complete before the application starts handling requests.

Purpose: - Run build tasks or asset compilation - Perform environment validation and checks - Pre-cache frequently accessed resources - Initialize external services or connections - Set up runtime configurations

Location: - Default: ignition/ directory at project root - Configurable: Specify a custom path in the manifest file

Execution: Ignition scripts run automatically during startup when present. They execute in sequence, and any errors will prevent the application from starting—ensuring your environment is properly configured before accepting traffic.

Example Ignition Script: 

// ValidateEnvironment.groovy
import spaceport.Spaceport

// Check required environment variables
def requiredVars = ['API_KEY', 'DATABASE_URL']
requiredVars.each { varName ->
    if (!System.getenv(varName)) {
        throw new RuntimeException("Required environment variable ${varName} is not set!")
    }
}

// Verify database connectivity
def db = Spaceport.main_memory_core
if (!db.isHealthy()) {
    throw new RuntimeException("Cannot connect to database!")
}

println "Environment validation passed!"

Learn More: See the Ignition Scripts Documentation for detailed patterns and use cases.

## Logging: Monitoring Application Activity

Effective logging is crucial for monitoring application health, debugging issues, and auditing events. Spaceport includes a built-in logging system that automatically tracks application activity.

Purpose: - Record application events, errors, and warnings - Track request processing and response times - Audit user actions and system changes - Provide diagnostic information for troubleshooting

Behavior: - Automatically creates daily log files named YYYY-MM-DD.log - Includes timestamps, severity levels, and contextual information - Rotates logs daily to prevent file size issues - Captures both framework-level and application-level logging

Location: - Default: logs/ directory at project root - Configurable: Specify a custom directory in the manifest file

Configuration: Customize logging behavior in your manifest:

logging:
  directory: logs/
  level: INFO
  includeStackTraces: true
Learn More: See the Logging Documentation for configuration options, log levels, and integration with monitoring tools.

# Best Practices for Scaffold Organization

## Start Simple, Grow Organically

Begin with the minimal structure needed for your current requirements. Add directories and components as your application grows. Premature optimization of structure can lead to unnecessary complexity.

# Start here
modules/
  App.groovy

# Grow to here as needed
modules/
  Router.groovy
  App.groovy
  services/
    EmailService.groovy
  documents/
    UserDocument.groovy

## Use Clear, Descriptive Names

Your scaffold's organization should be immediately understandable to new team members:

# Good: Clear purpose
modules/
  authentication/
    LoginHandler.groovy
    SessionManager.groovy
  api/
    UserEndpoints.groovy
    ArticleEndpoints.groovy

# Avoid: Unclear organization
modules/
  stuff/
    Handler1.groovy
    Manager.groovy
  things/
    Endpoints.groovy

## Separate Concerns

Keep different types of code in appropriate locations: - Business logic: Source modules - UI templates: Launchpad parts - Reusable components: Launchpad elements - Styling and client code: Static assets - One-time operations: Migrations - Startup tasks: Ignition scripts

## Document Your Structure

For custom scaffolds that deviate from conventions, include a README explaining: - Directory purposes and contents - Where new developers should add different types of code - Any non-standard conventions or patterns - Build or deployment considerations

## Consider Team Size

Small teams/solo developers: - Flatter structures work well - Less ceremony, faster development - Co-locate related code

Large teams: - Deeper hierarchies prevent conflicts - Clear boundaries reduce merge conflicts - Feature-based organization scales better

# Summary

Spaceport's flexible scaffolding system supports projects from single-file prototypes to large-scale applications. Key takeaways:

Core Principles: - Scaffolds define your project's organizational structure - Configuration happens through the manifest file (config.spaceport) - Spaceport supports both minimal and comprehensive structures - Choose the approach that matches your project's complexity

Scaffold Approaches: - --no-manifest: Fastest start, minimal features - Port-Echo: Clean slate with manifest configuration - Port-Mercury: Full-featured example application - CLI generation: Interactive, customizable setup

Key Components: - Source Modules: Application logic and routing - Static Assets: Images, CSS, JavaScript - Launchpad: Templates and reactive components - Migrations: Database evolution - Ignition: Pre-launch initialization - Logging: Automatic activity tracking

Best Practices: - Start simple and grow organically - Use clear, descriptive names - Separate concerns appropriately - Document custom structures - Scale structure with team size

With these patterns and principles, you can build a scaffold that enhances productivity, maintainability, and team collaboration throughout your application's lifecycle.

# See Also