Echo Starter API

A robust Go web application starter using the Echo framework. This project provides a solid foundation for building production-ready REST APIs with features like authentication, caching, email sending, and more.

Features

• Framework: Built with Echo web framework
• Database: PostgreSQL with connection pooling
• Caching: Redis integration
• Authentication: JWT-based auth with refresh tokens
• API Documentation: Auto-generated Swagger/OpenAPI docs
• Environment Config: Using godotenv
• External Services:
  • SendGrid for email delivery
  • OpenAI integration
  • Speechmatics API integration
• AWS Integration: Ready-to-use AWS configuration

Project Structure

.
├── cmd/
│   └── main.go                     # Application entry point with Swagger annotations
├── docs/                           # Swagger/OpenAPI documentation
│   ├── docs.go                     # Generated Swagger spec
│   ├── swagger.json               # Generated Swagger JSON
│   └── swagger.yaml               # Generated Swagger YAML
├── internal/
│   ├── app/                        # Application initialization
│   │   └── application.go         # App setup and configuration
│   ├── config/                     # Configuration management
│   │   └── config.go              # Configuration structs and loading
│   ├── db/                        # Database management
│   │   ├── migration/             # SQL migrations
│   │   │   ├── 20241111021715_create_users_table.up.sql
│   │   │   └── 20241111042819_create_posts_table.up.sql
│   │   ├── query/                 # SQL queries
│   │   │   ├── posts.sql
│   │   │   └── users.sql
│   │   ├── db.go                 # Database connection setup
│   │   └── schema.sql            # Database schema
│   ├── env/                       # Environment variable handling
│   │   └── env.go                # Environment utilities
│   ├── handler/                   # HTTP handlers
│   │   ├── handler.go            # Handler initialization
│   │   ├── health.go             # Health check handler
│   │   └── user.go               # User-related handlers
│   ├── server/                    # HTTP server setup
│   │   ├── routes.go             # Route definitions
│   │   ├── server.go             # Server configuration
│   │   └── start.go              # Server startup logic
│   ├── store/                     # Generated database code
│   │   ├── db.go                 # Database interface
│   │   ├── models.go             # Generated models
│   │   ├── posts.sql.go          # Generated post queries
│   │   ├── querier.go            # Query interface
│   │   └── users.sql.go          # Generated user queries
│   └── validator/                 # Request validation
│       └── validator.go           # Custom validator setup
├── .air.toml                      # Air configuration for hot reload
├── .env.example                   # Example environment variables
├── .gitignore                     # Git ignore rules
├── go.mod                         # Go module definition
├── go.sum                         # Go module checksums
├── Makefile                       # Build and development commands
├── README.md                      # Project documentation
└── sqlc.yaml                      # SQLC configuration

Prerequisites

• Go 1.21 or higher
• PostgreSQL
• Redis
• Make (for Makefile usage)
• Air (for hot reloading)
• DBMate (for database migrations)

Getting Started

1. Clone the repository

   git clone https://github.com/yourusername/echo-starter.git
   cd echo-starter

2. Copy environment file

   cp .env.example .env

3. Modify environment variables

   # Application
   APP_NAME=echo-starter
   APP_ENV=development
   APP_PORT=1323
   
   # Database
   DB_HOST=localhost
   DB_PORT=5432
   DB_NAME=echo_starter_db
   DB_USER=postgres
   DB_PASSWORD=postgres
   
   # Add other necessary variables...

4. Install dependencies

   go mod download
   make setup-dev

5. Run the application

   go run cmd/api/main.go

6. Run DBMate

   dbmate up

7. Run the Application

   air

API Documentation

Once the application is running, you can access the Swagger documentation at:

http://localhost:3000/swagger/index.html

Configuration

The application uses environment variables for configuration. See .env.example for all available options.

Development

Commit Message Validation

This project uses commitlint to validate commit messages.

Commit Messages must be in the following format:

<type>[optional scope]: <subject>

Valid types:
- feat: A new feature
- fix: A bug fix
- docs: Documentation only changes
- style: Changes that do not affect the meaning of the code (white-space, formatting etc)
- refactor: A code change that neither fixes a bug nor adds a feature
- perf: A code change that improves performance
- test: Adding missing tests or correcting existing tests
- build: Changes that affect the build system or external dependencies
- ci: Changes to our CI configuration files and scripts
- chore: Other changes that don't modify src or test files
- revert: Reverts a previous commit

Running Tests

go test ./...

Linting

golangci-lint run

Building

go build -o bin/api cmd/api/main.go

Deployment

Docker

docker build -t echo-starter .
docker run -p 3000:3000 echo-starter

Environment-Specific Config

• Development: .env.development
• Staging: .env.staging
• Production: .env.production

External Service Integration

SendGrid

Configure SendGrid for email delivery:

SENDGRID_API_KEY=your_api_key
SENDGRID_FROM_EMAIL=no-reply@yourapp.com
SENDGRID_FROM_NAME=Your App

OpenAI

Set up OpenAI integration:

OPENAI_API_KEY=your_api_key
OPENAI_MODEL=gpt-4
OPENAI_MAX_TOKENS=2000

Speechmatics

Configure Speechmatics API:

SPEECHMATICS_API_KEY=your_api_key
SPEECHMATICS_BASE_URL=https://asr.api.speechmatics.com/v2

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Echo Framework
• godotenv
• All other open-source packages used in this project

Support

For support, email your-email@example.com or open an issue in the GitHub repository.