AI-friendly architecture

Context compression, not inflated token claims

Marionette does not rely on exaggerated token-reduction percentages. The structural advantage is simpler: there are fewer moving parts to explain when the UI, server behavior, and state transitions live in one Go-oriented flow.

Instead of asking an AI tool to keep a SPA client, API contract, server handler, and duplicated state model in sync, you can describe the product behavior and point to the Go code that renders the screen and handles the action.

• One language, one context: keep product-flow explanations centered on Go.
• UI / Action / State in Go: make the cause-and-effect path explicit.
• Fewer frontend/backend boundaries: reduce the contracts an assistant must reconstruct.
• htmx partial updates: keep interactivity server-led without a full SPA mental model.

One language, one context

Admin screens and internal tools often need precise workflow changes: add an action, update a table, filter a chart, or gate a control by permissions. Marionette keeps those changes in Go so the relevant context stays close together.

For AI-assisted work, that means prompts can be framed around one implementation language and one server-side execution model instead of restating how separate frontend and backend projects coordinate. The assistant needs less architectural setup before it can discuss the actual workflow change.

UI / Action / State in Go

Marionette groups the things an AI assistant needs to reason about for operational UI: what the user sees, what action they can trigger, and how state changes after that action. Keeping UI / Action / State in Go makes the causal path explicit.

• UI: pages and components describe the visible admin workflow.
• Action: server-side handlers define what happens when the operator clicks or submits.
• State: shared Go state can drive coordinated widgets such as tables, filters, and charts.

Fewer frontend/backend boundaries

Every boundary between frontend and backend is another contract the team and the AI assistant must understand: request shapes, response shapes, client state, optimistic updates, validation, and error display.

Marionette does not remove every boundary, but it reduces the number of boundaries needed for typical admin and operations screens. That makes reviews and AI prompts more focused on the business workflow instead of cross-stack plumbing.

htmx partial updates

htmx gives Marionette a small browser-side interaction model: the server can return partial HTML for the part of the page that changed, while the browser swaps it into place.

This keeps interactivity without forcing a full SPA architecture. For AI-assisted development, the important point is not a guaranteed token percentage; it is that the assistant can reason about the update from the server-rendered component and the action that produced it.

No TypeScript build chain required for the core app

Marionette keeps application logic on the Go side, with htmx handling partial updates in the browser. The core app therefore does not need a TypeScript build chain or a SPA-oriented frontend toolchain to deliver typical admin and operations workflows.

This is a Go-first policy, not a claim that Marionette eliminates every byte of client JavaScript. Existing shared helpers such as overlay behavior can still provide presentation support, while product workflow, state transitions, and validation stay primarily in Go handlers.

See the UI architecture policy for new .ts / .tsx files.

CRUD admin benchmark

A simple benchmark page compares the same CRUD admin requirement in a SPA architecture and a Marionette architecture without claiming a token reduction rate before measured token counts exist.

Open the benchmark definition