Skip to main content

Stack9 Samples Documentation

Overview​

This samples documentation provides real-world JSON examples from production Stack9 applications. Each sample demonstrates specific patterns, configurations, and best practices that can be used as reference when building Stack9 applications. The samples are organized by component type and showcase diverse implementation patterns from three production systems:

  1. SLSF LDS - A lottery and donation subscription management system
  2. Arbor CRM - An arborist job management and tree assessment platform
  3. LandscapeQLD - A landscape industry recruitment and membership system

Sample Categories​

📊 Entities​

Entity definitions form the data model foundation of Stack9 applications. Our samples demonstrate:

  • Simple lookup entities for reference data
  • Complex business entities with workflows
  • Entities with relationships and nested grids
  • Custom UI component integration
  • File handling and document management

🖥️ Screens​

Screen configurations define the user interface. Examples include:

  • List views with advanced column rendering
  • Detail views with multiple query integration
  • Simple CRUD screens with form configuration
  • Drawer forms with external API integration
  • Custom component usage and workflow visualization

🔌 Connectors​

Connectors enable integration with external services. Samples cover:

  • REST API integrations with various authentication methods
  • Payment gateway connections
  • Public API services (Google Maps, address validation)
  • AWS service integrations (OpenSearch)
  • Environment-specific configurations

⚙️ Automations​

Automations implement business logic and process orchestration. Examples show:

  • Webhook endpoints for API creation
  • Entity lifecycle hooks (create, update, delete)
  • Scheduled tasks with cron expressions
  • Workflow state transition handling
  • Message queue processing
  • Conditional action execution

🔍 Queries​

Queries define data retrieval and manipulation operations. Samples demonstrate:

  • Simple entity retrieval with relationship loading
  • Complex SQL aggregations with window functions
  • CRUD operations (INSERT, UPDATE, DELETE)
  • Filtered list queries with pagination
  • External API integrations (Google Maps, third-party services)
  • Direct database operations vs API-based queries

How to Use These Samples​

For Learning​

Each sample includes:

  • Description: Detailed explanation of what the sample demonstrates
  • Use Case: Real-world scenario where this pattern is applied
  • Key Features: Bullet points highlighting important aspects
  • JSON Definition: The complete, production-tested JSON
  • Notes: Implementation details, gotchas, and tips

For Implementation​

  1. Find the Right Pattern: Browse samples to find patterns matching your needs
  2. Copy and Adapt: Use the JSON as a starting point for your implementation
  3. Understand the Context: Read descriptions to understand the pattern's purpose
  4. Follow Best Practices: Note the conventions and patterns used

Schema Accuracy​

⚠️ CRITICAL: These JSON schemas are production-tested and must be character-perfect. Incorrect schemas will cause application errors. Always validate your JSON before deployment.

Sample Index​

Entities​

Screens​

Connectors​

Automations​

Queries​

Pattern Recognition​

When selecting samples, consider these patterns:

Data Complexity​

  • Simple: Lookup entities, basic screens
  • Moderate: Entities with relationships, CRUD screens
  • Complex: Workflow entities, multi-query screens

Integration Level​

  • Standalone: Simple entities and screens
  • Internal: Queue processors, lifecycle hooks
  • External: Webhooks, API connectors

Business Logic​

  • Declarative: Simple field definitions
  • Reactive: Lifecycle hooks, triggers
  • Orchestrated: Workflows, conditional automations

Best Practices from Samples​

  1. Naming Conventions: Use consistent, descriptive keys
  2. Environment Variables: Store credentials and URLs as env vars
  3. Field Validation: Always include appropriate validation rules
  4. Workflow Design: Keep workflows linear when possible
  5. Queue Usage: Use appropriate priority levels
  6. Error Handling: Include timeout and retry configurations
  7. Documentation: Use descriptions for complex fields

Contributing​

These samples are extracted from production systems. When adding new samples:

  1. Ensure JSON is valid and tested
  2. Follow the documentation format
  3. Provide meaningful descriptions
  4. Include real use cases
  5. Highlight unique patterns

Version Compatibility​

These samples are compatible with Stack9 framework version 2.x and above. Some features may require specific Stack9 modules or configurations.