andurel

README

Andurel - Rails-like Web Framework for Go

Andurel is a comprehensive web development framework for Go that prioritizes development speed. Inspired by Ruby on Rails, it combines convention over configuration with Go's performance and type safety to help you build full-stack web applications incredibly fast.

Join the discord here

Why Andurel?

Development speed is everything. Andurel eliminates boilerplate and lets you focus on building features:

• Lightning Fast Setup - New projects ready in seconds with andurel new
• Instant Scaffolding - Generate complete CRUD resources with one command
• Live Reload - Hot reloading for Go, templates, and CSS with andurel run
• Type Safety Everywhere - SQLC for SQL, Templ for HTML, Go for logic
• Batteries Included - Echo, Datastar, background jobs, sessions, CSRF protection, telemetry, email support, optional extensions (auth, workflows, docker)
• Convention over Configuration - Sensible defaults that just work
• PostgreSQL-Backed - Built on PostgreSQL with River job queues, pgx driver, and UUID support

Core Technologies

• Echo - High-performance HTTP framework
• SQLC - Type-safe SQL code generation
• Templ - Type-safe HTML templates
• Datastar - Hypermedia-driven frontend interactivity (RC6)
• River - PostgreSQL-backed background jobs and workflows
• OpenTelemetry - Built-in observability
• PostgreSQL - Powerful open-source database with pgx driver and native UUID support
• Tailwind CSS or vanilla CSS - Choose your styling approach

Quick Start

Installation

go install github.com/mbvlabs/andurel@latest

Create Your First Project

Andurel gives you choices when creating a new project:

# Create a new project with defaults (PostgreSQL + Tailwind CSS)
andurel new myapp

# Or customize your styling:
andurel new myapp -c vanilla             # Use vanilla CSS instead of Tailwind

# Add extensions for common features:
andurel new myapp -e auth                # Add authentication
andurel new myapp -e workflows           # Add workflow orchestration
andurel new myapp -e docker              # Add Dockerfile for containerization
andurel new myapp -e auth,workflows,docker   # Add multiple extensions

cd myapp

# Configure environment
cp .env.example .env
# Edit .env with your database settings

# Run the development server (with live reload)
andurel run

Your app is now running at http://localhost:8080 with automatic reloading for Go, Templ, and CSS changes.

Generate Your First Resource

# Create a complete resource with model, controller, views, and routes
andurel generate resource Product

# Or use the shorthand
andurel g resource Product

This single command creates everything you need for a full CRUD interface.

Project Structure

Generated projects follow a clear, Rails-inspired structure:

myapp/
├── assets/              # Static assets (compiled CSS, images)
├── bin/                 # Compiled binaries (console, migration, run, tailwindcli)
├── cmd/
│   ├── app/            # Main web application
│   ├── console/        # Interactive database console
│   ├── migration/      # Migration runner
│   └── run/            # Development server orchestrator
├── clients/             # External service clients
│   └── mailpit.go      # Mailpit email client
├── config/              # Application configuration
│   ├── app.go          # Sessions, tokens, security
│   ├── database.go     # Database connection
│   ├── email.go        # Email configuration
│   ├── telemetry.go    # Logging, tracing, metrics config
│   └── config.go       # Main config aggregator
├── controllers/         # HTTP request handlers
│   ├── controller.go   # Base controller utilities
│   ├── cache.go        # Cache control utilities
│   ├── pages.go        # Page controllers
│   └── assets.go       # Asset serving
├── css/                 # Source CSS files (Tailwind input)
├── database/
│   ├── migrations/     # SQL migration files
│   ├── queries/        # SQLC query definitions
│   └── sqlc.yaml       # SQLC configuration
├── email/               # Email functionality
│   ├── email.go        # Email client and sending logic
│   ├── base_layout.templ    # Base email template layout
│   └── components.templ     # Reusable email components
├── models/              # Data models and business logic
│   ├── model.go        # Base model setup
│   └── internal/db/    # Generated SQLC code (do not edit)
├── queue/               # Background job processing
│   ├── jobs/           # Job definitions
│   ├── workers/        # Worker implementations
│   └── workflow/       # Workflow orchestration (workflows ext)
├── router/              # Routes and middleware
│   ├── router.go       # Main router setup
│   ├── routes/         # Route definitions
│   ├── cookies/        # Cookie and session helpers
│   └── middleware/     # Custom middleware
├── telemetry/           # Observability setup
│   ├── logger.go       # Structured logging
│   ├── tracer.go       # Distributed tracing
│   ├── metrics.go      # Application metrics
│   └── helpers.go      # Telemetry utilities
├── views/               # Templ templates
│   ├── *.templ         # Template source files
│   └── *_templ.go      # Generated Go code (do not edit)
├── .env.example         # Example environment variables
├── Dockerfile           # Container build (docker ext)
└── go.mod               # Go module definition

CLI Commands

Andurel provides a comprehensive CLI for all development tasks. Most commands have short aliases to speed up your workflow.

Development Server

# Run development server with hot reload for Go, Templ, and CSS
andurel run

This orchestrates Air (Go live reload), Templ watch, and Tailwind CSS compilation.

Code Generation

Generate complete resources or individual components with type-safe code:

# Generate everything: model + controller + views + routes
andurel generate resource Product
andurel g resource Product  # short alias

# Generate individual components
andurel generate model User              # Create model
andurel generate model User --refresh    # Refresh after schema changes
andurel generate model Product --table products_catalog  # Use custom table name
andurel generate controller User         # Controller only
andurel generate controller User --with-views  # Controller + views
andurel generate view User               # Views only
andurel generate view User --with-controller   # Views + controller

# Short aliases work too
andurel g model User
andurel gen controller Product --with-views

Database Migrations

# Create a new migration
andurel migration new create_users_table
andurel m new add_email_to_users  # short alias

# Run migrations
andurel migration up           # Apply all pending migrations
andurel m up                   # short alias

# Rollback migrations
andurel migration down         # Rollback last migration
andurel m down                 # short alias

# Advanced migration commands
andurel migration up-to [version]    # Apply up to specific version
andurel migration down-to [version]  # Rollback to specific version
andurel migration reset              # Reset and reapply all migrations
andurel migration fix                # Fix migration version gaps

SQLC Code Generation

# Generate type-safe Go code from SQL queries
andurel sqlc generate
andurel s generate     # short alias

# Validate SQL without generating code
andurel sqlc compile
andurel s compile      # short alias

App Management

# Open interactive database console
andurel app console
andurel a c          # short alias

Project Creation

# Create a new project with defaults (PostgreSQL + Tailwind CSS)
andurel new myapp

# Customize your styling:
andurel new myapp -c vanilla             # Use vanilla CSS

# Add extensions:
andurel new myapp -e auth                # Authentication
andurel new myapp -e workflows           # Workflow orchestration
andurel new myapp -e docker              # Docker containerization
andurel new myapp -e auth,workflows,docker   # Multiple extensions

# With custom GitHub repo:
andurel new myapp --repo username

LLM Documentation

# Output comprehensive framework docs for AI assistants
andurel llm

Key Features

Type Safety Everywhere

Andurel enforces type safety at every layer:

• SQLC - Generate type-safe Go code from SQL queries, catch errors at compile time
• Templ - Type-safe HTML templates with Go syntax, no runtime template errors
• Echo - Strongly-typed HTTP handlers and middleware
• Validation - Built-in struct validation with go-playground/validator

Flexible Model Generation

Models support flexible table name mapping for working with existing databases or custom naming conventions:

• Default Convention - Automatically pluralizes model names to table names (User → users)
• Custom Table Names - Override with --table flag to map to any table name
• Legacy Database Support - Work with existing schemas that don't follow Rails conventions

Background Jobs

Built-in background job processing with River, PostgreSQL-backed job queue:

// Define a job
type EmailJobArgs struct {
    UserID uuid.UUID
}

func (EmailJobArgs) Kind() string { return "email_job" }

// Enqueue anywhere in your app
insertOnly.Client.Insert(ctx, EmailJobArgs{UserID: userID}, nil)

Queue Management - RiverUI provides a web interface for monitoring and managing background jobs. Access it during development to view job status, retry failed jobs, and monitor queue performance.

PostgreSQL-Powered

Andurel is built on PostgreSQL for robust, production-ready applications:

• River Job Queue - Fast, reliable background job processing with built-in web UI
• UUID Support - Native UUID primary keys for distributed systems
• pgx Driver - High-performance PostgreSQL driver with connection pooling
• Type-Safe Queries - SQLC generates Go code from your SQL queries
• Workflow Orchestration - Complex multi-step processes with the workflows extension

Live Development Experience

andurel run orchestrates three watch processes:

1. Air - Rebuilds Go code on changes
2. Templ - Recompiles templates on save
3. Tailwind CSS - Regenerates styles as you write

Security Built-in

• CSRF Protection - Automatic token validation for non-API routes
• Session Management - Encrypted cookie sessions with gorilla/sessions
• Flash Messages - Built-in support for temporary user notifications
• Secure Defaults - Password hashing, SQL injection prevention, XSS protection

Email Support

Built-in email functionality for sending transactional emails and notifications:

• Template Support - Type-safe email templates using Templ
• Mailpit Integration - Pre-configured Mailpit client for development testing
• Flexible Configuration - Easy-to-configure SMTP settings via environment variables
• Ready to Use - Email infrastructure included in every new project by default

Telemetry and Observability

Built-in OpenTelemetry integration for comprehensive application monitoring:

• Structured Logging - JSON-formatted logs with configurable levels and exporters (stdout, file, OTLP)
• Distributed Tracing - Request tracing with support for Jaeger, Zipkin, and OTLP exporters
• Metrics Collection - Application metrics with Prometheus and OTLP exporters
• Resource Detection - Automatic environment and runtime metadata collection
• Production Ready - Pre-configured exporters and sensible defaults for immediate use

RESTful Routing

Fluent route builder with type-safe URL generation:

var UserShowPage = newRouteBuilder("show").
    SetNamePrefix("users").
    SetPath("/users/:id").
    SetMethod(http.MethodGet).
    SetCtrl("Users", "Show").
    WithMiddleware(auth.Required).
    RegisterWithID()

// Generate URLs type-safely
url := routes.UserShowPage.URL(userID)

Extensions

Andurel includes optional extensions that add common functionality to your projects:

• auth - Complete authentication system with login, registration, password reset, session management, and IP-based rate limiting for security
• workflows - River-based workflow orchestration for managing complex multi-step background processes with task dependencies
• docker - Production-ready Dockerfile and .dockerignore for containerized deployments

Add extensions when creating a project with the -e flag:

andurel new myapp -e auth
andurel new myapp -e workflows,docker
andurel new myapp -e auth,workflows,docker

Extensions integrate seamlessly with your chosen CSS framework, generating all necessary models, controllers, views, and routes.

Frontend Interactivity with Datastar

Andurel uses Datastar (RC6) for hypermedia-driven interactivity, allowing you to build dynamic user interfaces without writing JavaScript:

• Server-side rendering with progressive enhancement
• Reactive updates using HTML attributes
• Form validation and submission without page reloads
• Real-time updates and polling
• Clean separation between backend logic and frontend behavior
• Built-in helper functions for common form elements and patterns

Datastar keeps your application logic on the server while providing a smooth, modern user experience. Generated views include pre-built form elements and helpers to accelerate development.

Framework Philosophy

Andurel combines Rails conventions with Go's strengths:

1. Convention over Configuration - Sensible defaults, minimal setup
2. Development Speed First - Code generation eliminates boilerplate
3. Type Safety - Compile-time guarantees prevent runtime errors
4. MVC Architecture - Clear separation of concerns
5. RESTful Design - Standard HTTP patterns and routing

Development Workflow

Creating a New Feature

Here's a typical workflow for adding a new resource:

# 1. Create a migration for your database table
andurel m new create_products_table

# 2. Edit the migration file in database/migrations/
# Add your CREATE TABLE statement

# 3. Run the migration
andurel m up

# 4. Generate the complete resource (model + controller + views + routes)
andurel g resource Product

# 5. Start the development server
andurel run

# Your CRUD interface is ready at http://localhost:8080/products

Making Schema Changes

# 1. Create a migration
andurel m new add_description_to_products

# 2. Edit the migration file
# Add your ALTER TABLE statement

# 3. Apply the migration
andurel m up

# 4. Refresh the model to regenerate code
andurel g model Product --refresh

Working with Background Jobs

# 1. Define your job in queue/jobs/
# 2. Implement the worker in queue/workers/
# 3. Enqueue jobs from controllers or models using insertOnly.Client.Insert()

AI-Friendly

Andurel includes comprehensive documentation for AI assistants:

andurel llm

This outputs detailed framework information that helps AI coding assistants understand your project structure, available commands, and conventions. Paste this into your AI assistant's context for better code generation.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run quality checks: go vet ./... and golangci-lint run
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Development Setup

git clone https://github.com/mbvlabs/andurel
cd andurel
go mod download
go test ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.

Tech Stack

Andurel is built on top of excellent open-source projects:

• Echo - High-performance HTTP router and framework
• SQLC - Type-safe SQL code generation
• Templ - Type-safe Go templates
• Datastar - Hypermedia-driven frontend interactivity (RC6)
• River - Fast PostgreSQL-backed job queue and workflows
• OpenTelemetry - Observability framework for logs, traces, and metrics
• pgx - PostgreSQL driver and toolkit
• Air - Live reload for Go apps
• Tailwind CSS - Utility-first CSS framework (optional)
• Cobra - CLI framework

Acknowledgments

Inspired by Ruby on Rails and its philosophy that developer happiness and productivity matter. Built for developers who want to move fast without sacrificing type safety or code quality.

---