Wahoo is a Go, React, and Tailwind SaaS framework. Go owns public HTTP. React renders through a private Node SSR worker.

> **Work in progress:** Do not use Wahoo in production yet. APIs and templates can change.

## Start

```bash
go run ./cmd/wahoo new --local ./acme
```

The command creates a core application with explicit configuration, health/readiness routes, a private SSR boundary, strict JSON helpers, and a project metadata file.

## What Wahoo Provides

- Go HTTP lifecycle, request IDs in context, panic recovery, bounded logs, middleware, and request observations.
- Explicit security-header, body-limit, and rate-limit middleware contracts.
- Strict bounded JSON decoding with a stable error envelope.
- Password, opaque-token, session, CSRF, and tenant-authorization primitives.
- Migration/readiness contracts without a database driver lock-in.
- Bounded SSE/WebSocket transports with scoped event topics.
- Provider-neutral jobs, storage, mail, audit, webhook, entitlement, billing, and usage contracts.
- OpenAPI, worker, Docker supervisor, release installer, and conservative upgrade tooling.

## Modules

| Module | State |
| --- | --- |
| `auth`, `sse`, `websocket` | Browser-facing `501` stubs until application policy exists. |
| `openapi` | Serves an application-owned OpenAPI 3.1 document. |
| `jobs` | Adds a separate worker command that requires a queue adapter. |
| `uploads`, `mail`, `audit`, `webhooks`, `entitlements`, `billing` | Provider-neutral `501` integration seams. |

## Application Responsibilities

- Database driver, migrations, repositories, and backups.
- Cookie lifecycle, session storage, CSRF design, OAuth, and MFA.
- Tenant resolution, domain authorization, and shared rate-limit storage.
- Queue, object storage, mail, payment, and billing providers.
- Webhook replay protection, idempotency, audits, monitoring, and incident response.

## Guides

| Guide | Use it to |
| --- | --- |
| [Quick Start](quick-start.md) | Create, test, add modules, and upgrade a project. |
| [Application Foundations](application-foundations.md) | Configure APIs, sessions, tenants, readiness, and observations. |
| [Operations Primitives](operations-primitives.md) | Add jobs, storage, mail, audits, webhooks, and entitlements. |
| [Server and Routes](server-and-routes.md) | Register routes and return HTML or JSON. |
| [React SSR](react-ssr.md) | Run the private React renderer. |
| [Realtime](realtime.md) | Add authenticated realtime transports. |
| [Authentication](authentication.md) | Implement account and session flows. |
| [Production](production.md) | Build, secure, verify, and deploy the application. |