API Only Architecture: Headless Go Backend

Overview

The API-only architecture strips away everything except the Go backend. There is no React, no TypeScript, no Node.js, no pnpm, no Turborepo. You get a clean Go API that serves JSON endpoints and auto-generated API documentation at /docs. Test your endpoints with curl, Postman, or the built-in Scalar/Swagger UI.

Despite being the smallest architecture, it still includes every backend battery: authentication (JWT + OAuth), file storage (S3), email (Resend), background jobs (asynq), cron scheduling, Redis caching, AI integration, and TOTP two-factor auth. You get the full Go API -- you just bring your own frontend.

grit new myapp --api

Key Characteristics

Full Folder Structure

The project contains just the Go API inside apps/api/ plus root-level config files. No frontend directories, no packages directory, no TypeScript configuration.

Directory Breakdown

{
  "architecture": "api",
  "go_module": "myapp/apps/api"
}

Code Generation

Running grit generate resource in an API-only project creates only Go files. No Zod schemas, no TypeScript types, no React hooks, no admin pages.

Example: grit generate resource Post --fields "title:string,body:text,published:bool" creates 4 Go files (model, service, handler, and a <name>_import.go handler) and injects routes -- that's it.

Built-in API Endpoints

Every API-only project ships with these endpoints out of the box, before you generate any resources.

Data Flow

With no frontend, the data flow is straightforward. Clients send HTTP requests directly to the Go API.

Client (curl / Postman / mobile app / external frontend)
    │
    ├── POST /api/auth/login      → Auth handler → JWT service
    ├── GET  /api/posts            → Post handler → Post service → PostgreSQL
    ├── POST /api/uploads          → Upload handler → S3/MinIO
    ├── POST /api/ai/chat          → AI handler → Claude/OpenAI
    └── GET  /docs                 → Scalar/Swagger UI

Development Workflow

Development is simpler than any other architecture -- just one terminal for the Go server.

# Start infrastructure
docker compose up -d

# Run the API with hot reload
grit start server

# Test with curl
curl http://localhost:8080/api/health
curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name":"admin","email":"admin@example.com","password":"password123"}'

# Or open the API docs in your browser
open http://localhost:8080/docs

Deployment

Deploy the Go binary with Docker or directly. No frontend build step needed.

Docker

FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o server cmd/server/main.go

FROM alpine:3.19
WORKDIR /app
COPY --from=builder /app/server .
EXPOSE 8080
CMD ["./server"]

Docker Compose (production)

services:
  api:
    build:
      context: ./apps/api
      dockerfile: Dockerfile
    ports:
      - "8080:8080"
    env_file: .env
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:16-alpine
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${DB_PASSWORD}

  redis:
    image: redis:7-alpine

volumes:
  pgdata:

When to Choose API Only

Example Project