Documentation

Building Your First Application

This guide walks through the concepts and workflow of building a blog application, focusing on understanding the framework’s patterns rather than step-by-step code generation.

Application Overview

We’ll explore building a blog application with: - User management - Registration and authentication - Blog posts - Full CRUD operations - Comments - User interactions - Web interface - HTML views with Tailwind CSS - API endpoints - JSON API for all operations

Planning Your Application

1. Domain Modeling

Start by identifying your core entities and their relationships:

  • User - The foundation for authentication and authorship
  • BlogPost - Core content with title, content, and publishing state
  • Comment - User feedback tied to posts

Consider the relationships between entities: - Users author multiple blog posts - Blog posts can have many comments - Comments belong to both a post and an author

2. Database Design

Plan your schema with the framework’s patterns in mind:

  • Standard Fields - Every entity gets id, created_at, updated_at
  • Relationships - Foreign keys with proper constraints
  • Indexes - For common query patterns and relationships

3. Service Architecture Planning

For each entity, you’ll need:

  • Fetcher - Query capabilities with filtering
  • Handler - CRUD operations with validation
  • Hydrator - Relationship loading patterns
  • Molder - Form transformation logic
  • Serializer - Response formatting
  • Validator - Input validation rules

Development Workflow

Phase 1: Foundation (Users)

  1. Model Definition - Define User entity with authentication fields
  2. Database Layer - Create ESO and Table for SQL mapping
  3. Service Suite - Implement all user-related services
  4. Business Logic - Create registration/authentication Maestros
  5. Web Layer - Controllers and routes for user operations

Phase 2: Core Content (Blog Posts)

  1. Extend Models - Add BlogPost with author relationships
  2. Service Implementation - Full CRUD service suite
  3. Business Logic - Publishing workflows and permissions
  4. Relationships - Hydrator patterns for loading authors
  5. Web Interface - CRUD operations with rich forms

Phase 3: Interactions (Comments)

  1. Comment System - Models with nested relationships
  2. Complex Hydration - Loading posts, authors, and comments
  3. Permissions - Comment moderation and ownership
  4. Real-time Features - Consider WebSocket integration

Key Learning Concepts

Understanding the Maestro Pattern

Business operations are orchestrated through Mae modules:

  • Sequential Steps - Validation → Transformation → Persistence → Response
  • Dependency Injection - Services injected for testability
  • Error Handling - Structured error management throughout
  • Transaction Management - Ensuring data consistency

Service Integration Patterns

Learn how services work together:

  • Data Flow - Form → Molder → Mae → Handler → Database
  • Query Patterns - Fetcher → Hydrator → Serializer → Response
  • Validation Chain - Form validation → Business rules → Database constraints
  • Testing Strategy - Unit tests for services, functional tests for Maestros

Relationship Management

Understanding how entities connect:

  • Preset Hydration - Predefined relationship loading patterns
  • Batch Loading - Preventing N+1 queries through efficient batching
  • Deep Relationships - Loading nested entity relationships
  • Performance Optimization - Selective loading based on context

Development Best Practices

Start Simple, Extend Gradually

  • Begin with basic CRUD operations
  • Add complexity incrementally
  • Test each component before moving forward
  • Keep business logic in Maestros, not controllers

Follow Framework Conventions

  • Use ESO pattern for database operations
  • Implement complete service suites for entities
  • Create Mae modules for complex business logic
  • Test at appropriate levels (unit, functional, integration)

Plan for Growth

  • Design extensible relationship patterns
  • Consider caching strategies early
  • Plan API versioning if needed
  • Structure templates for reusability

Testing Your Application

Testing Strategy

  1. Unit Tests - Test services in isolation
  2. Functional Tests - Test Maestro business logic end-to-end
  3. Integration Tests - Test complete request cycles
  4. Manual Testing - Verify user experience and edge cases

What to Test

  • Validation Logic - Ensure proper input handling
  • Business Rules - Verify complex logic works correctly
  • Relationships - Test data loading and consistency
  • Error Scenarios - Verify graceful error handling

Deployment Considerations

Environment Setup

  • Configure different environments (dev, staging, prod)
  • Set up proper logging and monitoring
  • Plan database migration strategy
  • Configure static asset handling

Performance Planning

  • Implement appropriate caching layers
  • Plan for database query optimization
  • Consider CDN for static assets
  • Monitor application performance metrics

Next Steps

After building your first application:

  1. Explore Advanced Patterns - Study complex business logic patterns
  2. Learn Performance Optimization - Caching, query optimization, scaling
  3. Security Hardening - Authentication, authorization, data protection
  4. Testing Mastery - Advanced testing patterns and automation

Common Pitfalls to Avoid

  • Over-engineering early - Start simple, add complexity when needed
  • Skipping tests - Testing is integral to framework methodology
  • Ignoring relationships - Plan entity relationships from the start
  • Controller bloat - Keep business logic in Maestros, not controllers
  • Database anti-patterns - Follow ESO pattern consistently

The goal is to understand the framework’s philosophy and patterns deeply, enabling you to build robust, maintainable applications efficiently.

Quickstart
Configuration