Getting Started

This guide walks you through creating a new Go API project and generating your first module from scratch — from zero to running server in under five minutes.

1. Create a New Project

goclarc new my-api --db postgres --module-path github.com/you/my-api

--db controls which database driver is scaffolded (postgres | mongo | rtdb). It defaults to postgres.

This generates a complete project skeleton:

my-api/
  cmd/
    api/
      main.go                      # Gin server, DB connect, graceful shutdown
  internal/
    core/
      config/
        config.go                  # Environment-based Config struct
      db/
        db.go                      # Connect() — one shared pool for all modules
      errors/
        errors.go                  # AppError type + sentinel errors
      response/
        response.go                # OK(), Created(), Fail() helpers
    middleware/
      auth.go                      # x-user-id auth middleware stub
      error.go                     # Error → HTTP status mapping
      logger.go                    # Zap request logger
  go.mod
  .gitignore
  .env.example

Move into your project and fill in the database URL:

cd my-api
cp .env.example .env
# edit .env and set DATABASE_URL

2. Write a Schema

Create a directory for your schemas and write a YAML file:

mkdir schemas

schemas/user.yaml

module: user
table: users

fields:
  - name: id
    type: uuid
    primary: true
    auto: true           # generated by DB — skipped from Create params

  - name: email
    type: string
    required: true       # adds binding:"required" to CreateRequest

  - name: name
    type: string
    required: true

  - name: age
    type: int
    nullable: true       # *int32 in Entity, nil-safe in ToView()

  - name: is_active
    type: bool

  - name: created_at
    type: timestamp
    auto: true

  - name: updated_at
    type: timestamp
    nullable: true
    auto: true

3. Generate the Module

goclarc module user --db postgres --schema schemas/user.yaml

Output:

Generating module "user" (db: postgres) → internal/modules/user
  created  internal/modules/user/entity.go
  created  internal/modules/user/dto.go
  created  internal/modules/user/repository.go
  created  internal/modules/user/service.go
  created  internal/modules/user/handler.go
  created  internal/modules/user/routes.go
  created  schemas/queries/users.sql
  created  db/migrations/001_create_users.sql

4. Preview Before Writing

Use --dry-run to print the generated files to stdout without touching the filesystem:

goclarc module user --db postgres --schema schemas/user.yaml --dry-run

5. Wire the Module into main.go

Open cmd/api/main.go. The database connection is already set up — find the TODO comment and add your module:

import "github.com/you/my-api/internal/modules/user"

// The pool is already open — just pass it in:
userRepo    := user.NewRepository(pool)
userService := user.NewService(userRepo)
userHandler := user.NewHandler(userService)
user.RegisterRoutes(v1, userHandler, middleware.Auth())

Adding a second module uses the same pool — no second connection:

import "github.com/you/my-api/internal/modules/cart"

cartRepo    := cart.NewRepository(pool)
cartService := cart.NewService(cartRepo)
cartHandler := cart.NewHandler(cartService)
cart.RegisterRoutes(v1, cartHandler, middleware.Auth())

6. Apply the Migration

goclarc generated a CREATE TABLE statement at db/migrations/001_create_users.sql. Apply it to your database before starting the server:

psql $DATABASE_URL -f db/migrations/001_create_users.sql

The generated repository.go uses pgx/v5 directly with raw SQL — no sqlc setup or code generation step is needed.

7. Run the Server

go mod tidy
go run ./cmd/api

{"level":"info","ts":"...","msg":"database connected"}
{"level":"info","ts":"...","msg":"server started","port":3001}

Your endpoints are live:

Method	Path	Handler
POST	/api/v1/users	Create
GET	/api/v1/users	List
GET	/api/v1/users/:id	GetByID
PATCH	/api/v1/users/:id	Update
DELETE	/api/v1/users/:id	Delete

8. Enable Swagger UI (optional)

Pass --swagger to both commands to generate browsable API docs with zero extra dependencies:

# Recreate the project with --swagger (or start fresh)
goclarc new my-api --db postgres --module-path github.com/you/my-api --swagger

# Generate the module spec alongside the module code
goclarc module user --db postgres --schema schemas/user.yaml --swagger

# Copy the module spec into docs/openapi.yaml so the UI picks it up
cp docs/user.openapi.yaml docs/openapi.yaml

Start the server and open your browser:

http://localhost:3001/docs             → Swagger UI
http://localhost:3001/docs/openapi.yaml → raw OpenAPI 3.0 spec

The spec is generated directly from your schema — field types, required constraints, and nullable flags are all accurate at generation time. See the Generated Code Guide for details on docs/swagger.go and docs/openapi.yaml.

Next Steps

• Add a second module: goclarc module cart --db postgres --schema schemas/cart.yaml
• Read the Schema Reference to understand all field types
• Browse Examples for real-world patterns