# Irgo Framework - AI Assistant Guide

> This document instructs AI coding assistants on how to write applications using the Irgo framework.

## Framework Overview

Irgo is a mobile application framework that uses:
- **Go** as the backend runtime (compiled via gomobile)
- **Datastar** for frontend interactivity (SSE-based hypermedia)
- **templ** for type-safe HTML templates
- **WebView** to render the UI (iOS WKWebView, Android WebView)

The key insight: there's no network - SSE requests from Datastar are intercepted by the WebView and routed directly to Go handlers running in-process.

## Core Principles

1. **Hypermedia-Driven**: Return HTML fragments via SSE, not JSON. Datastar morphs HTML directly into the DOM.
2. **Server-Side State**: All state lives in Go. The WebView is a thin rendering layer.
3. **Signals for UI State**: Use Datastar signals for transient UI state (loading, modals, form inputs).
4. **Type Safety**: Use templ for compile-time template checking.

## Project Structure

When working on an Irgo project, expect this structure:

```
project/
├── main.go              # Entry point, dev server
├── app/app.go           # Router setup
├── handlers/            # HTTP handlers (business logic)
├── templates/           # templ files (.templ)
├── static/              # CSS, JS, images
├── mobile/mobile.go     # Mobile bridge
└── ios/                 # Xcode project
```

## Writing Handlers

### Handler Signatures

Irgo has two types of handlers:

```go
// Page handlers return (string, error) for full page renders
func(ctx *router.Context) (string, error)

// Datastar handlers return error and use ctx.SSE() for responses
func(ctx *router.Context) error
```

### Handler Examples

```go
// Page handler - return rendered template
r.GET("/", func(ctx *router.Context) (string, error) {
    return renderer.Render(templates.HomePage())
})

// Datastar GET handler
r.DSGet("/items/{id}", func(ctx *router.Context) error {
    id := ctx.Param("id")
    item, err := getItem(id)
    if err != nil {
        return ctx.NotFound("Item not found")
    }
    return ctx.SSE().PatchTempl(templates.ItemDetail(item))
})

// Datastar POST with signals
r.DSPost("/items", func(ctx *router.Context) error {
    var signals struct {
        Name string `json:"name"`
    }
    ctx.ReadSignals(&signals)

    item := createItem(signals.Name)

    sse := ctx.SSE()
    sse.PatchTempl(templates.ItemRow(item))
    sse.PatchSignals(map[string]any{"name": ""}) // Clear input
    return nil
})

// Datastar DELETE
r.DSDelete("/items/{id}", func(ctx *router.Context) error {
    id := ctx.Param("id")
    deleteItem(id)
    return ctx.SSE().RemoveElements("#item-" + id)
})
```

### Context Methods

```go
ctx.Param("name")           // URL path parameter: /users/{name}
ctx.Query("key")            // Query parameter: ?key=value
ctx.FormValue("field")      // Form field value
ctx.Header("X-Custom")      // Request header
ctx.IsDatastar()            // True if Datastar request
ctx.ReadSignals(&v)         // Parse Datastar signals into struct
ctx.SSE()                   // Get SSE writer for responses
ctx.Redirect("/path")       // Redirect
```

### SSE Response Methods

```go
sse := ctx.SSE()
sse.PatchTempl(component)   // Morph templ component into DOM
sse.PatchElements(id, html) // Morph raw HTML into element
sse.PatchSignals(signals)   // Update client-side signals
sse.RemoveElements(selector)// Remove elements from DOM
sse.Redirect(url)           // Navigate to new URL
sse.Console(level, msg)     // Log to browser console
```

## Writing Templates

### Template Syntax (templ)

templ uses Go-like syntax with HTML:

```go
package templates

// Component with parameters
templ Button(text string, action string) {
    <button data-on:click={ action }>{ text }</button>
}

// Component with children
templ Card(title string) {
    <div class="card">
        <h2>{ title }</h2>
        <div class="card-body">
            { children... }
        </div>
    </div>
}

// Using components
templ HomePage() {
    @Layout("Home") {
        @Card("Welcome") {
            <p>Hello, world!</p>
            @Button("Learn More", "@get('/about')")
        }
    }
}

// Conditional rendering
templ UserStatus(user *User) {
    if user != nil {
        <span>Welcome, { user.Name }</span>
    } else {
        <a href="/login">Sign In</a>
    }
}

// Loops
templ ItemList(items []Item) {
    <ul>
        for _, item := range items {
            <li>{ item.Name }</li>
        }
    </ul>
}

// Conditional classes
templ TodoItem(todo Todo) {
    <div class={ "todo", templ.KV("completed", todo.Done) }>
        { todo.Title }
    </div>
}

// Dynamic attributes
templ Input(name string, value string, required bool) {
    <input
        type="text"
        name={ name }
        value={ value }
        required?={ required }
    />
}
```

### Layout Pattern

Always use a layout component for full pages:

```go
templ Layout(title string) {
    <!DOCTYPE html>
    <html lang="en">
    <head>
        <meta charset="UTF-8"/>
        <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
        <title>{ title }</title>
        <link rel="stylesheet" href="/static/css/output.css"/>
        <script type="module" src="/static/js/datastar.js"></script>
    </head>
    <body>
        { children... }
    </body>
    </html>
}

templ AboutPage() {
    @Layout("About") {
        <main class="container">
            <h1>About Us</h1>
        </main>
    }
}
```

### Fragment Pattern

For Datastar partial updates, return just the fragment:

```go
// Full page (initial load)
templ TodosPage(todos []Todo) {
    @Layout("Todos") {
        <main>
            <h1>My Todos</h1>
            @TodoList(todos)
            @AddTodoForm()
        </main>
    }
}

// Fragment (for Datastar updates)
templ TodoList(todos []Todo) {
    <div id="todo-list">
        for _, todo := range todos {
            @TodoItem(todo)
        }
    </div>
}

// Single item fragment (identified by ID)
templ TodoItem(todo Todo) {
    <div id={ "todo-" + todo.ID } class="todo-item">
        { todo.Title }
    </div>
}
```

## Datastar Patterns

### Core Attributes

```html
<!-- Initialize signals -->
<div data-signals="{name: '', count: 0}">

<!-- Two-way binding -->
<input data-bind:name type="text" />

<!-- Display signal value -->
<span data-text="$name"></span>

<!-- Conditional display -->
<div data-show="$isVisible">Shown when true</div>

<!-- Dynamic classes -->
<div data-class:active="$isActive">Toggles 'active' class</div>
```

### Event Handling

```html
<!-- Click with GET request -->
<button data-on:click="@get('/api/data')">Load</button>

<!-- Click with POST request -->
<button data-on:click="@post('/api/items')">Create</button>

<!-- Submit form with signals -->
<form data-signals="{title: ''}" data-on:submit__prevent="@post('/items')">
    <input data-bind:title />
    <button type="submit">Add</button>
</form>

<!-- Debounced input for search -->
<input data-on:keyup__debounce.300ms="@get('/search')" />

<!-- Throttled mouse tracking -->
<div data-on:mousemove__throttle.100ms="@get('/track')">
```

### Event Modifiers

- `__debounce.Xms` - Wait for pause in events
- `__throttle.Xms` - Limit event frequency
- `__prevent` - Prevent default
- `__stop` - Stop propagation
- `__once` - Fire only once

### Initialization

```html
<!-- Load data on mount -->
<div data-init="@get('/api/initial-data')">
    Loading...
</div>
```

## Common Patterns

### CRUD Operations

```go
// handlers/items.go
package handlers

type Item struct {
    ID    string
    Name  string
}

var items = make(map[string]Item)

func MountItems(r *router.Router, renderer *render.TemplRenderer) {
    // List (full page)
    r.GET("/items", func(ctx *router.Context) (string, error) {
        list := getItems()
        return renderer.Render(templates.ItemsPage(list))
    })

    // Create (Datastar handler)
    r.DSPost("/items", func(ctx *router.Context) error {
        var signals struct {
            Name string `json:"name"`
        }
        ctx.ReadSignals(&signals)

        item := createItem(signals.Name)

        sse := ctx.SSE()
        sse.PatchTempl(templates.ItemRow(item))
        sse.PatchSignals(map[string]any{"name": ""})
        return nil
    })

    // Read
    r.DSGet("/items/{id}", func(ctx *router.Context) error {
        id := ctx.Param("id")
        item, ok := items[id]
        if !ok {
            return ctx.NotFound("Item not found")
        }
        return ctx.SSE().PatchTempl(templates.ItemDetail(item))
    })

    // Update
    r.DSPatch("/items/{id}", func(ctx *router.Context) error {
        id := ctx.Param("id")
        var signals struct {
            Name string `json:"name"`
        }
        ctx.ReadSignals(&signals)

        item := updateItem(id, signals.Name)
        return ctx.SSE().PatchTempl(templates.ItemRow(item))
    })

    // Delete
    r.DSDelete("/items/{id}", func(ctx *router.Context) error {
        id := ctx.Param("id")
        deleteItem(id)
        return ctx.SSE().RemoveElements("#item-" + id)
    })
}
```

### Search/Filter

```go
// templates/search.templ
templ SearchForm() {
    <div data-signals="{query: ''}">
        <input
            type="search"
            data-bind:query
            data-on:keyup__debounce.300ms="@get('/search')"
            placeholder="Search..."
        />
        <div id="results"></div>
    </div>
}

// handlers/search.go
r.DSGet("/search", func(ctx *router.Context) error {
    var signals struct {
        Query string `json:"query"`
    }
    ctx.ReadSignals(&signals)

    results := search(signals.Query)
    return ctx.SSE().PatchTempl(templates.SearchResults(results))
})
```

### Infinite Scroll

```go
templ ItemListWithPagination(items []Item, page int, hasMore bool) {
    for i, item := range items {
        if i == len(items)-1 && hasMore {
            <div data-intersect={ fmt.Sprintf("@get('/items?page=%d')", page+1) }>
                @ItemRow(item)
            </div>
        } else {
            @ItemRow(item)
        }
    }
}
```

### Tabs

```go
templ TabContainer() {
    <div data-signals="{activeTab: 'one'}">
        <div class="tabs">
            <button
                data-class:active="$activeTab === 'one'"
                data-on:click="$activeTab = 'one'; @get('/tab/one')"
            >
                Tab 1
            </button>
            <button
                data-class:active="$activeTab === 'two'"
                data-on:click="$activeTab = 'two'; @get('/tab/two')"
            >
                Tab 2
            </button>
        </div>
        <div id="tab-content">
            @TabOne()
        </div>
    </div>
}
```

### Modal Dialog

```go
templ ModalTrigger() {
    <div data-signals="{showModal: false}">
        <button data-on:click="$showModal = true">
            Open Modal
        </button>

        <div class="modal-backdrop" data-show="$showModal" data-on:click="$showModal = false">
            <div class="modal" data-on:click__stop="">
                <h2>Confirm Action</h2>
                <p>Are you sure?</p>
                <button data-on:click="@post('/action'); $showModal = false">
                    Confirm
                </button>
                <button data-on:click="$showModal = false">
                    Cancel
                </button>
            </div>
        </div>
    </div>
}
```

### Form Validation

```go
templ FormField(name, label, value, error string) {
    <div class="field">
        <label for={ name }>{ label }</label>
        <input
            type="text"
            id={ name }
            data-bind={ name }
            data-on:blur="@post('/validate/' + name)"
            class={ templ.KV("error", error != "") }
        />
        <span id={ name + "-error" } class="error-message">
            { error }
        </span>
    </div>
}

// Handler
r.DSPost("/validate/email", func(ctx *router.Context) error {
    var signals struct {
        Email string `json:"email"`
    }
    ctx.ReadSignals(&signals)

    if !isValidEmail(signals.Email) {
        return ctx.SSE().PatchTempl(templates.ValidationError("email", "Invalid email address"))
    }
    return ctx.SSE().RemoveElements("#email-error")
})
```

## Real-Time Updates

Datastar uses SSE natively for all interactions. For server push, use long-running SSE connections:

### Polling

```go
templ LiveStatus() {
    <div
        data-init="@get('/status')"
        data-on:load__interval.5s="@get('/status')"
    >
        <div id="status">Checking...</div>
    </div>
}
```

### Server Push

```go
import "github.com/stukennedy/irgo/pkg/datastar"

// Create hub
hub := datastar.NewHub()
go hub.Run()

// Handle SSE connections
r.GET("/events", func(ctx *router.Context) error {
    return hub.HandleSSE(ctx.ResponseWriter, ctx.Request,
        datastar.WithRoom("dashboard"),
    )
})

// Push updates from anywhere
func updateDashboard(stats Stats) {
    html := renderer.RenderToString(templates.DashboardStats(stats))
    hub.BroadcastToRoom("dashboard", datastar.PatchElements(html))
}
```

## Mobile-Specific Patterns

### Safe Area Handling

```go
templ MobileLayout(title string) {
    <!DOCTYPE html>
    <html>
    <head>
        <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover"/>
        <style>
            body {
                padding-top: env(safe-area-inset-top);
                padding-bottom: env(safe-area-inset-bottom);
                padding-left: env(safe-area-inset-left);
                padding-right: env(safe-area-inset-right);
            }
        </style>
    </head>
    <body>
        { children... }
    </body>
    </html>
}
```

### Touch-Friendly Buttons

```go
templ MobileButton(text string) {
    <button class="min-h-[44px] min-w-[44px] p-3 touch-manipulation">
        { text }
    </button>
}
```

## Do's and Don'ts

### DO:

1. **Return HTML via SSE** from Datastar handlers
2. **Use templ** for all HTML generation
3. **Use signals** for UI state (loading, modals, form inputs)
4. **Use ctx.SSE().PatchTempl()** for DOM updates
5. **Use element IDs** to target where updates go
6. **Use ctx.SSE().PatchSignals()** to update client state
7. **Keep handlers simple** - one responsibility each
8. **Use Layout for full pages**, fragments for partial updates

### DON'T:

1. **Don't return JSON** - this is hypermedia, not an API
2. **Don't use JavaScript frameworks** - Datastar handles interactivity
3. **Don't manipulate DOM in JavaScript** - let Datastar do it
4. **Don't store business state in signals** - keep it in Go
5. **Don't use hx-* attributes** - use data-* Datastar attributes
6. **Don't forget element IDs** - Datastar needs them to target updates
7. **Don't return full pages for Datastar requests** - return fragments

## File Naming Conventions

- Handlers: `handlers/*.go` (e.g., `handlers/items.go`)
- Templates: `templates/*.templ` (e.g., `templates/items.templ`)
- Generated: `templates/*_templ.go` (auto-generated, don't edit)
- Layouts: `templates/layout.templ`
- Components: `templates/components.templ`
- Pages: `templates/<name>.templ` (e.g., `templates/home.templ`)

## Testing Patterns

```go
// handlers/items_test.go
func TestCreateItem(t *testing.T) {
    r := setupTestRouter()
    client := irgotest.NewClient(r.Handler())

    // Test Datastar request
    resp := client.Datastar().PostJSON("/items", map[string]any{
        "name": "Test Item",
    })

    resp.AssertOK(t)
    resp.AssertSSEEvent(t, "datastar-patch-elements")
    resp.AssertContains(t, "Test Item")
}
```

## Quick Reference

### Router

```go
r.GET("/path", pageHandler)      // Full page
r.DSGet("/path", datastarHandler) // Datastar SSE
r.DSPost("/path", datastarHandler)
r.DSPut("/path", datastarHandler)
r.DSPatch("/path", datastarHandler)
r.DSDelete("/path", datastarHandler)
r.Route("/prefix", func(r *router.Router) { ... })
r.Static("/static", "static")
```

### Context

```go
ctx.Param("id")          // URL param
ctx.Query("key")         // Query string
ctx.FormValue("name")    // Form field
ctx.IsDatastar()         // Is Datastar request?
ctx.ReadSignals(&v)      // Parse signals
ctx.SSE()                // Get SSE writer
ctx.Redirect("/path")    // Redirect
```

### SSE Writer

```go
sse := ctx.SSE()
sse.PatchTempl(component)     // Morph component
sse.PatchElements(id, html)   // Morph raw HTML
sse.PatchSignals(signals)     // Update signals
sse.RemoveElements(selector)  // Remove elements
sse.Redirect(url)             // Navigate
```

### Datastar Attributes

```html
data-signals="{...}"          <!-- Initialize signals -->
data-bind:name                <!-- Two-way binding -->
data-text="$signal"           <!-- Display signal -->
data-show="$condition"        <!-- Conditional display -->
data-class:name="$cond"       <!-- Conditional class -->
data-on:event="action"        <!-- Event handler -->
data-on:event__mod="action"   <!-- With modifier -->
data-init="action"            <!-- On mount -->
data-intersect="action"       <!-- On viewport entry -->
```

### Datastar Actions

```html
@get('/path')                 <!-- GET request -->
@post('/path')                <!-- POST request -->
@put('/path')                 <!-- PUT request -->
@patch('/path')               <!-- PATCH request -->
@delete('/path')              <!-- DELETE request -->
$signal = value               <!-- Update signal -->
$signal++                     <!-- Increment signal -->
```

### templ Syntax

```go
templ Name(args) { }           // Define component
@Component()                   // Use component
{ variable }                   // Output value
{ children... }                // Slot for children
if cond { } else { }           // Conditional
for _, x := range xs { }       // Loop
class={ templ.KV("a", bool) }  // Conditional class
attr?={ bool }                 // Conditional attribute
```