realworld-backend

.
├── cmd/api/                    # Application entry point
│   ├── main.go                # Server initialization
│   ├── routes.go              # Route definitions
│   ├── handlers (*.go)        # HTTP handlers
│   ├── middleware.go          # Authentication, recovery, etc.
│   ├── *_test.go              # Integration tests
│   └── openapi.yml            # API specification
├── internal/
│   ├── auth/                  # JWT token generation & validation
│   ├── data/                  # Data models and operations
│   │   ├── articles.go        # Article CRUD, favorites, feed
│   │   ├── users.go           # User management, authentication
│   │   ├── comments.go        # Comment operations
│   │   ├── tags.go            # Tag management
│   │   └── store.go           # Store interfaces and initialization
│   ├── validator/             # Input validation utilities
│   └── vcs/                   # Version information
├── migrations/                 # Database schema migrations
├── docker-compose.yml         # PostgreSQL container definition
└── Taskfile.yml               # Development task definitions

The database schema consists of 6 main tables with the following relationships:

erDiagram
    users ||--o{ articles : "authors"
    users ||--o{ comments : "writes"
    users ||--o{ favorites : "favorites"
    users ||--o{ follows : "follower"
    users ||--o{ follows : "followed"
    articles ||--o{ comments : "has"
    articles ||--o{ favorites : "favorited_by"
    
    users {
        bigserial id PK
        citext username UK
        citext email UK
        bytea password_hash
        text bio
        text image
        integer version
    }
    
    articles {
        serial id PK
        varchar slug UK
        varchar title
        text description
        text body
        text_array tag_list
        timestamp created_at
        timestamp updated_at
        integer favorites_count
        integer author_id FK
        integer version
    }
    
    comments {
        serial id PK
        text body
        integer article_id FK
        bigint author_id FK
        timestamp created_at
        timestamp updated_at
    }
    
    favorites {
        integer user_id PK_FK
        integer article_id PK_FK
    }
    
    follows {
        integer follower_id PK_FK
        integer followed_id PK_FK
    }
    
    tags {
        serial id PK
        varchar tag UK
    }

Key Relationships:

• users → articles: One-to-many (a user can create many articles)
• users → comments: One-to-many (a user can write many comments)
• users ↔ users (via follows): Many-to-many (users can follow each other)
• users ↔ articles (via favorites): Many-to-many (users can favorite many articles)
• articles → comments: One-to-many (an article can have many comments)
• tags: Standalone table for tag persistence (articles store tags in tag_list array)

Indexes:

• Articles: slug, author_id, created_at, tag_list (GIN index)
• Comments: article_id, author_id, created_at
• Favorites: user_id, article_id
• Tags: tag
• Follows: Composite primary key on (follower_id, followed_id)

Quick Start (Recommended)

# Starts Postgres + runs migrations + starts server
task server:start

Manual Start

# Build the binary
task server:build

# Run with custom configuration
./bin/api \
  -port 8080 \
  -env production \
  -db-dsn $DB_DSN \
  -jwt-secret $JWT_SECRET

Configuration Options

./bin/api -help

Flags:
  -port int
        API server port (default 4000)
  -env string
        Environment (development|staging|production) (default "development")
  -db-dsn string
        PostgreSQL DSN (required)
  -db-max-open-conns int
        PostgreSQL max open connections (default 25)
  -db-max-idle-time duration
        PostgreSQL max connection idle time (default 15m)
  -jwt-secret string
        JWT secret key (required)
  -jwt-issuer string
        JWT issuer (default "realworld-api")

This project uses Task for managing common development workflows. All tasks are defined in Taskfile.yml.

Key Tasks

Development

# Start the server (auto-starts Postgres, runs migrations)
task server:start

# Build the binary
task server:build

# View all available command-line flags
task server:help

Database Management

# Start Postgres container
task docker:postgres:start

# Stop Postgres container
task docker:postgres:stop

# Create a new migration
task db:migrations:new -- create_some_table

# Run migrations
task db:migrations:up

# Rollback migrations
task db:migrations:down

# Setup database (create)
task db:setup

# Teardown database (drop)
task db:teardown

Testing & Quality

# Run all unit tests with coverage
task test

# Visualize coverage report
task visualize:coverage

# Run Newman API integration tests
task newman

# Run linters, formatters, and security checks
task audit

Dependencies

# Install required tools (migrate, golangci-lint, etc.)
task install:dependencies

# Update all Go dependencies
task update:dependencies

Environment Variables

All tasks automatically use environment variables defined in Taskfile.yml:

env:
  DB_DSN: postgres://postgres:postgres@localhost:5432/conduit?sslmode=disable
  JWT_SECRET: some-secret
  JWT_ISSUER: conduit

Edit these values in Taskfile.yml to customize your local development environment.

Query Parameters for List Articles:

• tag - Filter by tag name
• author - Filter by author username
• favorited - Filter by username who favorited
• limit - Max articles to return (default: 20, max: 100)
• offset - Number of articles to skip (default: 0)