# Gofasta

> The official documentation for the Gofasta Go backend toolkit and CLI.

Gofasta is split across two repositories: `github.com/gofastadev/cli` (the CLI) and `github.com/gofastadev/gofasta` (the library). A scaffolded project is plain Go code the developer owns — no runtime framework, no custom compiler.

## Overview

- [Overview](https://gofasta.dev/docs): The official documentation for the Gofasta Go backend toolkit and CLI.
- [White Paper](https://gofasta.dev/docs/white-paper): Gofasta technical white paper — design principles, architecture, code generation strategy, dependency injection with Google Wire, database layer with GORM, HTTP routing with chi, authentication, background processing, real-time communication, email and notifications, file storage, internationalization, feature flags, observability, resilience patterns, security defaults, testing, deployment, and adoption path for Go web services.

## Getting Started

- [Introduction](https://gofasta.dev/docs/getting-started/introduction): What is Gofasta and why use it.
- [Installation](https://gofasta.dev/docs/getting-started/installation): Install the Gofasta CLI tool.
- [Quick Start](https://gofasta.dev/docs/getting-started/quick-start): Scaffold a project, start the full dev loop with one command, and ship your first resource — in under five minutes.
- [Project Structure](https://gofasta.dev/docs/getting-started/project-structure): Understand the directory layout of a Gofasta project.

## Guides

- [REST API](https://gofasta.dev/docs/guides/rest-api): Building REST APIs with Gofasta -- controllers, routes, DTOs, middleware, and response helpers.
- [GraphQL](https://gofasta.dev/docs/guides/graphql): Building GraphQL APIs with gqlgen in Gofasta -- schemas, resolvers, queries, mutations, and subscriptions.
- [Database & Migrations](https://gofasta.dev/docs/guides/database-and-migrations): Database setup, GORM models, migrations, multi-database support, and relationships in Gofasta.
- [Authentication](https://gofasta.dev/docs/guides/authentication): JWT authentication, login and registration flows, middleware, Casbin RBAC, and token refresh in Gofasta.
- [Code Generation](https://gofasta.dev/docs/guides/code-generation): Using the Gofasta CLI to generate models, services, controllers, scaffolds, and more.
- [Background Jobs](https://gofasta.dev/docs/guides/background-jobs): Cron scheduling, async task queues, job definitions, and recurring jobs in Gofasta.
- [Email & Notifications](https://gofasta.dev/docs/guides/email-and-notifications): Sending emails with SMTP, SendGrid, and Brevo, using HTML templates, and notification channels in Gofasta.
- [Testing](https://gofasta.dev/docs/guides/testing): Test setup, testcontainers-backed integration tests, mocking, and the testutil/testdb helper.
- [Deployment](https://gofasta.dev/docs/guides/deployment): Deploy Gofasta applications to a VPS with the built-in gofasta deploy command — Docker or compiled binary via SSH, with systemd, nginx, and GitHub Actions wired up.
- [Configuration](https://gofasta.dev/docs/guides/configuration): Application configuration with config.yaml, environment variable overrides, database settings, JWT, Redis, and feature flags in Gofasta.

## guides/debugging

- [Overview](https://gofasta.dev/docs/guides/debugging/overview): The local dev dashboard — trace waterfalls, per-request logs, N+1 detection, EXPLAIN plans, pprof, replay, and the zero-cost build-tag model behind them.
- [Guided Tour](https://gofasta.dev/docs/guides/debugging/guided-tour): Walk through a realistic debug session using the dashboard — slow endpoint → trace drill-down → stack → logs → SQL pattern → fix → replay.
- [Dashboard Panels](https://gofasta.dev/docs/guides/debugging/dashboard-panels): Reference for every panel on the dev dashboard — what it shows, where the data comes from, and any interactive affordances.
- [Tracing & Waterfalls](https://gofasta.dev/docs/guides/debugging/tracing): What's auto-traced, how to add spans to existing code, wiring SQL as waterfall bars, and instrumenting async tasks and cron jobs.
- [How It Works](https://gofasta.dev/docs/guides/debugging/architecture): The Wire + middleware + OTel wiring that gives you deep visibility without dirtying business code, plus the endpoint reference and the production-safety build-tag model.
- [Customization](https://gofasta.dev/docs/guides/debugging/customization): Ring sizes and rotation behavior, disabling individual devtools hooks, where the devtools code lives in your project, library coupling.

## CLI Reference

- [gofasta new](https://gofasta.dev/docs/cli-reference/new): Create a new Gofasta project with a complete Go web application scaffold.
- [gofasta init](https://gofasta.dev/docs/cli-reference/init): Initialize a cloned or existing Gofasta project by installing dependencies and running code generators.
- [gofasta dev](https://gofasta.dev/docs/cli-reference/dev): Bring the full local environment up with one command — compose services + migrations + Air hot reload, with interactive restart.
- [gofasta debug](https://gofasta.dev/docs/cli-reference/debug): CLI surface for the devtools /debug/* endpoints — requests, SQL, traces, logs, errors, cache, pprof, EXPLAIN, HAR, plus the composed diagnostics (last-slow-request, last-error, watch).
- [gofasta ai](https://gofasta.dev/docs/cli-reference/ai): Install per-agent configuration for Claude Code, Cursor, OpenAI Codex, Aider, and Windsurf — permission allowlists, hooks, project rules, and slash commands. Opt-in, idempotent, and extends to any MCP-aware successor.
- [gofasta verify](https://gofasta.dev/docs/cli-reference/verify): Run the full preflight gauntlet — gofmt, vet, golangci-lint, tests, build, Wire drift, routes — in one command.
- [gofasta status](https://gofasta.dev/docs/cli-reference/status): Report the health of the current project — Wire drift, swagger drift, pending migrations, uncommitted generated files, module freshness.
- [gofasta inspect](https://gofasta.dev/docs/cli-reference/inspect): Show the full composition of a resource — model fields, DTOs, service methods, controller methods, routes — as structured output.
- [gofasta do](https://gofasta.dev/docs/cli-reference/do): Run a named development workflow — a pre-defined chain of gofasta commands that together accomplish one higher-level task.
- [gofasta config](https://gofasta.dev/docs/cli-reference/config): Inspect and validate your project's config.yaml — currently the schema emitter, more subcommands to come.
- [gofasta serve](https://gofasta.dev/docs/cli-reference/serve): Start the Gofasta production HTTP server.
- [gofasta migrate](https://gofasta.dev/docs/cli-reference/migrate): Run database migrations up or down for your Gofasta project.
- [gofasta seed](https://gofasta.dev/docs/cli-reference/seed): Run database seeders to populate your database with initial or test data.
- [gofasta db](https://gofasta.dev/docs/cli-reference/db): Database management commands for resetting and managing your development database.
- [gofasta deploy](https://gofasta.dev/docs/cli-reference/deploy): Deploy a Gofasta application to a remote VPS via SSH using Docker or a compiled binary.
- [gofasta wire](https://gofasta.dev/docs/cli-reference/wire): Regenerate Google Wire dependency injection code for your Gofasta project.
- [gofasta swagger](https://gofasta.dev/docs/cli-reference/swagger): Generate OpenAPI/Swagger documentation from code annotations.
- [gofasta routes](https://gofasta.dev/docs/cli-reference/routes): Display all registered API routes in a formatted table.
- [gofasta console](https://gofasta.dev/docs/cli-reference/console): Start an interactive Go REPL to explore your project code.
- [gofasta doctor](https://gofasta.dev/docs/cli-reference/doctor): Check system prerequisites, project configuration, and database connectivity.
- [gofasta upgrade](https://gofasta.dev/docs/cli-reference/upgrade): Upgrade the Gofasta CLI to the latest version.
- [gofasta version](https://gofasta.dev/docs/cli-reference/version): Display the CLI version, Go version, and OS/architecture details.

## Code Generators

- [scaffold](https://gofasta.dev/docs/cli-reference/generate/scaffold): Generate a complete CRUD resource with all layers including model, repository, service, controller, routes, DTOs, migration, and DI provider.
- [model](https://gofasta.dev/docs/cli-reference/generate/model): Generate a GORM database model with typed fields and a corresponding migration pair.
- [repository](https://gofasta.dev/docs/cli-reference/generate/repository): Generate a model, migration, repository interface, and repository implementation for database access.
- [service](https://gofasta.dev/docs/cli-reference/generate/service): Generate a service interface and implementation containing business logic, along with all prerequisite layers.
- [controller](https://gofasta.dev/docs/cli-reference/generate/controller): Generate a REST controller with CRUD handlers and all prerequisite layers.
- [dto](https://gofasta.dev/docs/cli-reference/generate/dto): Generate request and response Data Transfer Objects (DTOs) for a resource.
- [migration](https://gofasta.dev/docs/cli-reference/generate/migration): Generate up and down SQL migration files for a database table.
- [route](https://gofasta.dev/docs/cli-reference/generate/route): Generate REST route definitions for a resource.
- [resolver](https://gofasta.dev/docs/cli-reference/generate/resolver): Patch the GraphQL resolver to add a service dependency for a resource.
- [provider](https://gofasta.dev/docs/cli-reference/generate/provider): Generate a Google Wire dependency injection provider set for a resource.
- [job](https://gofasta.dev/docs/cli-reference/generate/job): Generate a scheduled background job that implements the scheduler.Job interface.
- [task](https://gofasta.dev/docs/cli-reference/generate/task): Generate an async task handler using hibiken/asynq.
- [email-template](https://gofasta.dev/docs/cli-reference/generate/email-template): Generate an HTML email template for transactional emails.

## Package Library

- [Config](https://gofasta.dev/docs/api-reference/config): Configuration loading, database setup, and environment variable overrides for Gofasta applications.
- [Logger](https://gofasta.dev/docs/api-reference/logger): Structured logging with configurable levels, context-aware fields, and multiple output formats.
- [Errors](https://gofasta.dev/docs/api-reference/errors): Custom error types, HTTP error responses, error wrapping, and standardized error codes.
- [Models](https://gofasta.dev/docs/api-reference/models): Base model with UUID primary keys, automatic timestamps, soft delete, optimistic locking via record_version, and is_active/is_deletable flags.
- [HTTP Utilities](https://gofasta.dev/docs/api-reference/http-utilities): Request binding, response helpers, JSON utilities, and pagination support for HTTP handlers.
- [Middleware](https://gofasta.dev/docs/api-reference/middleware): HTTP middleware for CORS, rate limiting, logging, authentication, panic recovery, and request ID injection.
- [GraphQL](https://gofasta.dev/docs/api-reference/graphql): Shared GraphQL schema fragments for pagination, sorting, errors, and the health probe.
- [Auth](https://gofasta.dev/docs/api-reference/auth): JWT token generation and validation, claims management, auth middleware, and Casbin RBAC setup.
- [Cache](https://gofasta.dev/docs/api-reference/cache): In-memory and Redis caching with TTL support, cache strategies, and key management.
- [Storage](https://gofasta.dev/docs/api-reference/storage): File storage abstraction with local and S3 drivers, upload/download, and signed URL generation.
- [Mailer](https://gofasta.dev/docs/api-reference/mailer): Email sending with SMTP, SendGrid, and Brevo drivers, template rendering, and attachments.
- [Slack](https://gofasta.dev/docs/api-reference/slack): Outbound Slack messaging via incoming webhooks or bot tokens, with file uploads and threading support.
- [WhatsApp](https://gofasta.dev/docs/api-reference/whatsapp): Outbound WhatsApp messaging via UltraMsg, Twilio, or Meta Cloud API — with media attachments and threaded replies.
- [Push Notifications](https://gofasta.dev/docs/api-reference/push): Outbound mobile push notifications via Firebase Cloud Messaging, with a provider-pluggable Sender interface.
- [Notifications](https://gofasta.dev/docs/api-reference/notifications): Multi-channel notification dispatch for email, SMS, Slack, and in-app (database) delivery.
- [WebSocket](https://gofasta.dev/docs/api-reference/websocket): WebSocket server with room management, broadcasting, client lifecycle, and message handling.
- [Scheduler](https://gofasta.dev/docs/api-reference/scheduler): Cron-based job scheduling with job registration, schedule expressions, and lifecycle management.
- [Queue](https://gofasta.dev/docs/api-reference/queue): Async task processing with Redis using hibiken/asynq for background workers, retry policies, and concurrency control.
- [Resilience](https://gofasta.dev/docs/api-reference/resilience): Circuit breaker, retry with backoff, and fault-tolerance patterns using failsafe-go.
- [Validators](https://gofasta.dev/docs/api-reference/validators): Input validation built on go-playground/validator/v10 with custom validators registered via struct tags.
- [i18n](https://gofasta.dev/docs/api-reference/i18n): Internationalization with YAML locale files, message translation, and Accept-Language header detection.
- [Observability](https://gofasta.dev/docs/api-reference/observability): Prometheus metrics and OpenTelemetry tracing for application instrumentation.
- [Feature Flags](https://gofasta.dev/docs/api-reference/feature-flags): Feature flag evaluation through the OpenFeature Go SDK. Swap providers (in-memory, Flagd, LaunchDarkly, go-feature-flag, custom) without touching application code.
- [Sessions](https://gofasta.dev/docs/api-reference/sessions): Server-side HTTP session management with cookie and filesystem stores, backed by gorilla/sessions.
- [Encryption](https://gofasta.dev/docs/api-reference/encryption): AES-256-GCM encryption and decryption for securing sensitive data.
- [Seeds](https://gofasta.dev/docs/api-reference/seeds): Database seeding with GORM using a simple registry of seed functions with ordered execution.
- [Types](https://gofasta.dev/docs/api-reference/types): Shared DTO types, pagination inputs, sorting, and common API response types used across Gofasta packages.
- [Utils](https://gofasta.dev/docs/api-reference/utils): Pagination helpers, string conversion utilities, query building, and common helper functions.
- [Health](https://gofasta.dev/docs/api-reference/health): Liveness and readiness probe endpoints for load balancers, uptime monitors, and orchestrator health checks, with dependency status reporting.
- [Test Utilities](https://gofasta.dev/docs/api-reference/test-utilities): Test helpers for database setup with testcontainers, migrations, and PostgreSQL test databases.