# GoForj

> The composable stack for building with Go. Build Go applications with one cohesive application model, explicit wiring, local-first drivers, and production-ready primitives.

GoForj gives Go applications one consistent way to serve HTTP, run commands and background work, schedule tasks, use database, cache, storage, mail, auth, and metrics, and operate in production. Dependencies remain explicit through compile-time wiring, and every first-party library also works independently. Code created by GoForj is ordinary Go with clear application or framework ownership.

## About

- [What Is GoForj?](https://goforj.dev/about): Understand what GoForj provides, the problems it addresses, and when it fits a Go project.

## Versions

- [Versions](https://goforj.dev/versions): Version policy and historical milestone model for GoForj.
- [Changelog](https://goforj.dev/versions/changelog): Historical GoForj framework milestones and user-facing changes.

## Getting Started

- [Getting Started](https://goforj.dev/getting-started): Start here to build and understand a GoForj application.
- [Configuration](https://goforj.dev/getting-started/configuration): Learn which GoForj configuration layer to change and when an App needs a restart or rebuild.
- [Project Structure](https://goforj.dev/getting-started/project-structure): Learn where GoForj application behavior, app exposure, wiring, configuration, and generated output belong.
- [Quickstart](https://goforj.dev/getting-started/quickstart): Create, run, request, and test a new GoForj Project.
- [Choose a Starter Kit](https://goforj.dev/getting-started/starter-kits): Choose a frontend starting point and understand what changing it replaces.

## Cookbook

- [Cookbook](https://goforj.dev/cookbook): A task index for GoForj. Find the page that answers a "how do I" question without reading the whole manual.

## Drivers

- [Drivers](https://goforj.dev/drivers): Every interchangeable driver across GoForj's six swap primitives, in one place.

## Core Concepts

- [Core Concepts](https://goforj.dev/core): The framework model behind GoForj Apps, runtimes, providers, drivers, and generated components.
- [App Lifecycle](https://goforj.dev/core/app-lifecycle): How a GoForj App is constructed, starts, executes work, and shuts down.
- [Apps](https://goforj.dev/core/apps): Understand App identity, ownership, composition, and multi-app relationships in a GoForj Project.
- [Code Generation](https://goforj.dev/core/code-generation): Understand why GoForj generates code, who owns each result, and which changes require regeneration.
- [Dependency Injection](https://goforj.dev/core/dependency-injection): Follow a dependency from its provider through Wire to App construction.
- [Drivers and Adapters](https://goforj.dev/core/drivers-and-adapters): The difference between interchangeable infrastructure drivers and integration adapters in GoForj.
- [Local-First Development](https://goforj.dev/core/local-first-development): How GoForj keeps local development simple while preserving production infrastructure flexibility.
- [Named Resources](https://goforj.dev/core/named-resources): How GoForj Apps expose named caches, disks, queues, event buses, metrics, jobs, schedules, and routes.
- [Provider Patterns](https://goforj.dev/core/provider-patterns): Practical provider examples for typed configuration, required adapters, optional features, and multiple outbound integrations in GoForj Apps.
- [Runtime Topology](https://goforj.dev/core/runtime-topology): Understand when an app runs HTTP, workers, and schedules together or in separate processes.

## Building Applications

- [API Index and OpenAPI](https://goforj.dev/applications/api-index): Discover, publish, and serve an App-scoped HTTP contract and its OpenAPI projection.
- [Applications](https://goforj.dev/applications): Build HTTP services, commands, controllers, middleware, mail delivery, and application services with GoForj.
- [Commands](https://goforj.dev/applications/commands): How application commands run, receive dependencies, and delegate to services in GoForj Apps.
- [Controllers](https://goforj.dev/applications/controllers): How to write thin HTTP controllers that translate requests into application service calls.
- [HTTP Clients](https://goforj.dev/applications/http-clients): Build outbound HTTP clients in GoForj Apps with explicit construction, diagnostics, and safe dump behavior.
- [HTTP Services](https://goforj.dev/applications/http-services): Orient an HTTP service around its runtime, route composition, controllers, configuration, and operations.
- [Mail](https://goforj.dev/applications/mail): Send application and auth email through default and named GoForj mailers.
- [Middleware](https://goforj.dev/applications/middleware): How middleware is applied around HTTP handlers in GoForj Apps.
- [Requests and Validation](https://goforj.dev/applications/requests-validation): How controllers bind, normalize, validate, and pass request input into services.
- [Responses and Errors](https://goforj.dev/applications/responses-errors): How GoForj Apps should shape HTTP responses and error behavior.
- [Routes](https://goforj.dev/applications/routes): How routes are registered, grouped, protected, listed, and operated in GoForj Apps.
- [Application Services](https://goforj.dev/applications/services): How to organize business behavior behind controllers, commands, jobs, events, and schedules.

## Data and Persistence

- [Data and Persistence](https://goforj.dev/data): Durable data, cache, storage, transactions, repositories, and driver selection in GoForj.
- [Cache Patterns](https://goforj.dev/data/cache-patterns): How to use generated cache accessors for temporary, derived, and performance-oriented data.
- [Database Connections](https://goforj.dev/data/database-strategy): How GoForj Apps model database connections, driver support, and durable data ownership.
- [Driver Selection](https://goforj.dev/data/driver-selection): How to choose local and production drivers for database, cache, storage, queue, event, and mail infrastructure.
- [Migrations](https://goforj.dev/data/migrations): How GoForj Apps create, run, rollback, and organize database migrations.
- [Repositories](https://goforj.dev/data/repositories): How repositories isolate persistence behavior from services and runtime boundaries.
- [Storage Patterns](https://goforj.dev/data/storage-patterns): How to use generated storage disks for files, blobs, local disks, object stores, and remote filesystems.
- [Transactions](https://goforj.dev/data/transactions): How to reason about database transaction boundaries in GoForj services.

## Async and Workflows

- [Async and Workflows](https://goforj.dev/async): Events, queues, jobs, workers, scheduler processes, retries, and idempotency in GoForj.
- [Event Subscribers](https://goforj.dev/async/event-subscribers): How event subscribers react to typed events without becoming hidden workflow containers.
- [Events versus Queues](https://goforj.dev/async/events-vs-queues): Choose events for fan-out and queues/jobs for durable background work.
- [Events](https://goforj.dev/async/events): How GoForj Apps publish typed facts through local or distributed event buses.
- [Jobs](https://goforj.dev/async/jobs): How to define named queued work with typed payloads and handlers.
- [Queues](https://goforj.dev/async/queues): How GoForj Apps configure default and named queues for background work.
- [Retries and Idempotency](https://goforj.dev/async/retries-idempotency): How to design jobs, subscribers, and schedules that can safely run more than once.
- [Scheduler](https://goforj.dev/async/scheduler): How GoForj Apps define recurring work through the scheduler registry.
- [Workers](https://goforj.dev/async/workers): How queue workers run jobs, handle shutdown, and fit into GoForj runtime topology.

## Security

- [Security](https://goforj.dev/security): Authentication, sessions, cookies, refresh behavior, and security-sensitive GoForj application behavior.
- [Security Assurance](https://goforj.dev/security/assurance): GoForj security scope, automated controls, repository coverage, evidence, limitations, and enterprise review guidance.
- [Auth](https://goforj.dev/security/auth): Generated GoForj authentication, server-side sessions, cookies, refresh behavior, password reset, email verification, and inspect visibility.
- [Security Controls](https://goforj.dev/security/controls): Automated GoForj security controls, the evidence they produce, their limits, and the policies that keep findings actionable.
- [Enterprise Assessment](https://goforj.dev/security/enterprise-assessment): A practical evidence checklist for evaluating GoForj and separating ecosystem controls from deployment responsibilities.
- [OAuth](https://goforj.dev/security/oauth): Configure generated OAuth provider login and explicit account linking on top of GoForj Auth.
- [Production Hardening](https://goforj.dev/security/production-hardening): Security checks for deploying GoForj Apps with auth, cookies, mail, observability, and infrastructure drivers.
- [Repository Coverage](https://goforj.dev/security/repository-coverage): Every repository included in the GoForj security assurance baseline, its control profile, and links to current evidence.
- [Sessions and Cookies](https://goforj.dev/security/sessions-cookies): Understand GoForj access cookies, refresh cookies, server-authoritative sessions, rotation, revocation, and CSRF boundaries.
- [Source and Build Integrity](https://goforj.dev/security/source-build-integrity): Verify an approved GoForj module version, the installed CLI, generated source, and enterprise build artifacts.
- [Threat Model](https://goforj.dev/security/threat-model): GoForj trust boundaries, protected assets, threat scenarios, mitigations, deployment responsibilities, and residual risks.
- [Vulnerability Management](https://goforj.dev/security/vulnerability-management): How GoForj receives, evaluates, remediates, documents, and discloses security findings.

## Frontend

- [Frontend Integration](https://goforj.dev/frontend): How app-owned frontend source is built, embedded, and served by a GoForj App.
- [React Starter Kit](https://goforj.dev/frontend/react-starter-kit): How the React starter kit is generated, owned, built, and served inside a GoForj App.
- [templ + htmx Starter Kit](https://goforj.dev/frontend/templ-htmx-starter-kit): Build a server-rendered Go application with templ components, htmx navigation, and a small frontend asset pipeline.
- [Vue Starter Kit](https://goforj.dev/frontend/vue-starter-kit): How the Vue starter kit is generated, owned, built, and served inside a GoForj App.

## Starter Kits

- [Starter Kits](https://goforj.dev/starter-kits): Start with Vue, React, or templ + htmx, with account pages, settings, and local UI components.

## Performance

- [Performance](https://goforj.dev/performance): Benchmarking is a first-class engineering concern at GoForj, alongside coverage and integration testing. Compare published latency, throughput, and allocation measurements with reproducible workloads and source data.

## Testing

- [Testing](https://goforj.dev/testing): Test GoForj applications, services, commands, queues, events, cache, storage, and rendered Apps.
- [Cache and Storage Tests](https://goforj.dev/testing/cache-storage-tests): How to test cache and storage behavior with local drivers and targeted backend integration tests.
- [Command Tests](https://goforj.dev/testing/command-tests): How to test GoForj App commands without turning them into shell-script integration tests.
- [Event Tests](https://goforj.dev/testing/event-tests): How to test typed event publication and subscriber behavior.
- [HTTP Tests](https://goforj.dev/testing/http-tests): How to test controllers, route groups, health checks, readiness, and middleware behavior.
- [Integration Tests](https://goforj.dev/testing/integration-tests): How to test GoForj behavior that depends on generated wiring, databases, containers, or external backends.
- [Job and Queue Tests](https://goforj.dev/testing/job-queue-tests): How to test queued jobs, handlers, dispatch behavior, and worker boundaries.
- [Rendered Project Smoke Tests](https://goforj.dev/testing/rendered-app-smoke-tests): How GoForj contributors validate templates and generators through disposable rendered Projects.
- [Unit Tests](https://goforj.dev/testing/unit-tests): How to test GoForj application services and pure behavior without booting the full App.

## Verified Scenarios

- [Runnable Scenarios](https://goforj.dev/scenarios): End-to-end GoForj examples that show how Apps are built, wired, run, tested, and observed.
- [Cached User Profile](https://goforj.dev/scenarios/cached-user-profile): Add a repository and named cache resource to the JSON API route scenario.
- [Add a Database-Backed Resource](https://goforj.dev/scenarios/create-photo-data-resource): Follow the schema-first workflow from migration through a generated model, registered repository, and application-owned query.
- [File Upload to Storage](https://goforj.dev/scenarios/file-upload-storage): Add an upload endpoint that writes files to a named GoForj storage disk.
- [JSON API Route](https://goforj.dev/scenarios/json-api-route): Build a JSON API route with a controller, service, Wire provider, route registration, and test.
- [Reports Daily Schedule](https://goforj.dev/scenarios/reports-daily-schedule): Schedule reports:daily recurring work that dispatches existing reports:generate jobs.
- [Reports Generate Job](https://goforj.dev/scenarios/reports-generate-job): Dispatch reports:generate work from a users.created subscriber and process it with a queue worker.
- [Runtime Observability](https://goforj.dev/scenarios/runtime-observability): Follow a GoForj workflow through routes, logs, metrics, inspects, Lighthouse, workers, and scheduler runs.
- [Users Created Event](https://goforj.dev/scenarios/users-created-event): Publish a typed users.created event and handle it with a lifecycle-registered subscriber.

## Operations

- [Operations](https://goforj.dev/operations): Run, observe, inspect, and deploy GoForj applications with explicit runtime behavior.
- [Backup and Restore](https://goforj.dev/operations/backups): Plan, create, verify, retain, and safely restore GoForj App data.
- [Deploy an App](https://goforj.dev/operations/deployment-basics): Build, configure, release, verify, and roll back a GoForj App.
- [Health and Readiness](https://goforj.dev/operations/health-readiness): How GoForj Apps expose liveness and readiness checks.
- [HTTP Server](https://goforj.dev/operations/http-server): Operational behavior for generated GoForj HTTP runtimes.
- [Inspects](https://goforj.dev/operations/inspects): Runtime execution records for requests, jobs, scheduler runs, and commands.
- [Lighthouse](https://goforj.dev/operations/lighthouse): GoForj local and operator-facing runtime visibility.
- [Logging](https://goforj.dev/operations/logging): Operational logging guidance for GoForj Apps.
- [Metrics](https://goforj.dev/operations/metrics): Operational metrics emitted by GoForj Apps.
- [Performance Benchmarks](https://goforj.dev/operations/performance-benchmarks): Run and interpret Lighthouse browser benchmarks for HTTP, cache, queues, storage, and databases.
- [Queue Workers](https://goforj.dev/operations/queue-workers): Operational behavior for queue worker runtimes.
- [Runtime Processes](https://goforj.dev/operations/runtime-processes): How HTTP, workers, scheduler, and combined runtime processes start and stop.
- [Scheduler Processes](https://goforj.dev/operations/scheduler-processes): Operational behavior for generated scheduler runtimes.

## Developer Tools

- [Developer Tools](https://goforj.dev/developer-tools): GoForj CLI tooling, local App lifecycle orchestration, rendering, and App development workflows.
- [Atlas Debug Recipes](https://goforj.dev/developer-tools/atlas-debug-recipes): Evidence-first Atlas workflows for common GoForj debugging tasks.
- [Atlas Evaluation Program](https://goforj.dev/developer-tools/atlas-evaluations): How GoForj measures whether Atlas helps coding agents produce working, framework-conformant application changes.
- [Atlas](https://goforj.dev/developer-tools/atlas): Agent support for GoForj projects, including local guidance, skills, and MCP context.
- [Local Development with forj dev](https://goforj.dev/developer-tools/forj-dev): Run the complete GoForj development loop with one command: dependencies, migrations, frontend builds, App rebuilds, and safe runtime replacement.
- [Reading Wire Errors](https://goforj.dev/developer-tools/reading-wire-errors): How to interpret missing provider, duplicate provider, wrong set, and interface wiring failures in GoForj Apps.
- [Wiring Recipes](https://goforj.dev/developer-tools/wiring-recipes): Where to register application services, adapters, controllers, commands, jobs, repositories, and named resources in a GoForj App.

## Libraries

- [Libraries](https://goforj.dev/libraries): Standalone first-party GoForj libraries for Go services, CLIs, workers, and GoForj Apps.
- [Atlas Library for Go](https://goforj.dev/atlas): Project context, skills, diagnostics, and MCP tooling for GoForj coding agents.
- [Cache Library for Go](https://goforj.dev/cache): One cache API with local, distributed, and database-backed stores.
- [Collections Library for Go](https://goforj.dev/collection): Fluent, typed collection operations for Go with explicit mutation behavior.
- [Console Library for Go](https://goforj.dev/console): Semantic CLI output, ANSI-aware layout, prompts, loaders, and progress.
- [Crypt Library for Go](https://goforj.dev/crypt): Encryption helpers with key generation and rotation support.
- [Env Library for Go](https://goforj.dev/env): Layered environment loading and typed configuration helpers for Go.
- [Events Library for Go](https://goforj.dev/events): Typed event publication and subscription with local and distributed transports.
- [ExecX Library for Go](https://goforj.dev/execx): Command execution helpers with streaming, decoding, and TTY support.
- [GoDump Library for Go](https://goforj.dev/godump): Readable, configurable value dumps for debugging Go programs.
- [HTTPX Library for Go](https://goforj.dev/httpx): HTTP client helpers for typed requests, authentication, retries, and diagnostics.
- [Mail Library for Go](https://goforj.dev/mail): Portable message composition with local, SMTP, and provider delivery drivers.
- [Metrics Library for Go](https://goforj.dev/metrics): Counters, gauges, histograms, snapshots, and Prometheus-compatible export.
- [Queue Library for Go](https://goforj.dev/queue): Queued work, workers, retries, workflows, and pluggable backend drivers.
- [Scheduler Library for Go](https://goforj.dev/scheduler): Recurring work primitives with cron, intervals, overlap protection, and runtime controls.
- [Storage Library for Go](https://goforj.dev/storage): Named file and object-storage disks with local and remote drivers.
- [Strings Library for Go](https://goforj.dev/strings): Rune-safe string construction, matching, transformation, and inflection helpers.
- [Web Library for Go](https://goforj.dev/web): Server-side HTTP contracts, routing, middleware, testing, and an Echo-backed runtime.
- [Wire Library for Go](https://goforj.dev/wire): Fast, explicit compile-time dependency injection for Go.

## Reference

- [Reference](https://goforj.dev/reference): Framework-level lookup material for GoForj CLI commands, environment variables, configuration, generated files, and errors.
- [CLI Reference](https://goforj.dev/reference/cli): Framework-level lookup for common GoForj CLI commands.
- [Configuration Reference](https://goforj.dev/reference/configuration): Lookup reference for GoForj project configuration and runtime configuration layers.
- [Environment Reference (.env)](https://goforj.dev/reference/env-vars): Complete GoForj environment reference covering environment variables, env vars, config vars, .env files, dotenv configuration, drivers, runtime, and local services.
- [Errors](https://goforj.dev/reference/errors): Common GoForj error categories and where to investigate them.
- [File Ownership](https://goforj.dev/reference/generated-files): Identify which GoForj Project files belong to your application, the Framework, generators, or build tooling.
- [Generation Commands](https://goforj.dev/reference/generation-commands): Lookup reference for GoForj code generation commands.
- [Make Command Reference](https://goforj.dev/reference/make-commands): Lookup reference for GoForj make commands, generated files, registration changes, and shared options.
- [Naming Conventions](https://goforj.dev/reference/naming-conventions): Lookup reference for commands, jobs, schedules, events, routes, and named resources in GoForj Apps.

## Blog

- [Blog](https://goforj.dev/blog): Notes on GoForj design, framework direction, and production Go application development.
- [The composable stack for building with Go](https://goforj.dev/blog/the-composable-stack-for-building-with-go): Why GoForj exists, what kind of Go applications it is designed for, and how its framework and libraries fit together.

## Other

- [GoForj Landing Illustration](https://goforj.dev/hero-engine): Frontend choices, Atlas coding-agent support, libraries, and infrastructure surround the GoForj mark, with one app container moving through Harbor to Ship.
- [The GoForj Foundry](https://goforj.dev/hero-foundry): An interactive illustration of interchangeable infrastructure wired into one Go app.
- [Original GoForj Illustration](https://goforj.dev/hero-original): The original GoForj application forge illustration.
- [GoForj performance social preview](https://goforj.dev/performance-preview): A capture-ready composition using the performance page's recorded benchmark data.
- [Original GoForj site preview](https://goforj.dev/site-preview-original): A capture-ready social preview composition derived from the GoForj landing page.
- [GoForj site preview](https://goforj.dev/site-preview): A capture-ready social preview composition derived from the GoForj landing page.