Skip to main content

​
Overview

The backend is built with Go 1.23, Echo framework, and MongoDB. It provides RESTful API endpoints for user authentication and management.

​
Prerequisites

  • Go 1.23 or higher
  • MongoDB (local or Atlas)
  • Make (for build commands)

​
Installation

​
1. Navigate to Backend Directory

cd backend/

​
2. Install Dependencies

The project uses Go modules. Dependencies are defined in go.mod: 
module backend

go 1.23

require (
    github.com/golang-jwt/jwt/v5 v5.2.1
    github.com/google/uuid v1.6.0
    github.com/gorilla/sessions v1.4.0
    github.com/joho/godotenv v1.5.1
    github.com/labstack/echo/v4 v4.13.3
    github.com/samueltuyizere/validate_rw_phone_numbers v1.0.1
    go.mongodb.org/mongo-driver v1.17.1
    golang.org/x/crypto v0.31.0
)
Install all dependencies: 
go mod download

​
Environment Configuration

​
1. Create Environment File

Copy the example environment file: 
cp .env.example .env

​
2. Configure Environment Variables

Edit .env with your configuration:
​
APP_ENV
string
required
Application environment (development, staging, or production)
​
MONGODB_URI
string
required
MongoDB connection string (e.g., mongodb://localhost:27017 or Atlas URI)
​
PORT
string
required
Server port number (e.g., 8080)
​
SESSION_KEY
string
required
Secret key for JWT signing and session encryption (use a strong random string)
​
REDIS_URL
string
Redis connection URL for caching (optional)
The .env file is loaded automatically via github.com/joho/godotenv/autoload imported in main.go. Never commit this file to version control.

​
Example Configuration

.env
APP_ENV=development
MONGODB_URI=mongodb://localhost:27017
PORT=8080
SESSION_KEY=your-super-secret-key-change-this-in-production
REDIS_URL=redis://localhost:6379

​
Running the Server

​
Development Mode

Run the server with automatic reloading: 
make run
This executes go run main.go and starts the server on the configured port.

​
Build and Run

Build the binary and run: 
make build
./main

​
Live Reload (with Air)

For automatic reloading during development: 
make watch
This command will prompt to install Air if not already installed.

​
Server Initialization

The server initialization in main.go:16-31 follows this sequence:
main.go
func main() {
    var app = echo.New()
    app.Use(middleware.Logger())
    app.Use(middleware.Recover())
    app.Use(middleware.CORS())

    configs.ConnectDB()

    // public routes
    app.POST("/register", auth.HandleUserRegistration)
    app.POST("/login", auth.HandleUserLogin)

    port := fmt.Sprintf(":%s", configs.EnvPort())
    log.Fatal(app.Start(port))
}

​
Middleware Stack

  1. Logger - Logs all HTTP requests
  2. Recover - Recovers from panics
  3. CORS - Enables cross-origin requests

​
Database Connection

The configs.ConnectDB() function establishes MongoDB connection on startup. The database name is automatically set to {APP_ENV}-backend.

​
Docker Support

Run MongoDB and other dependencies with Docker: 
# Start containers
make docker-run

# Stop containers
make docker-down

​
Testing

Run tests: 
make test
No tests are currently implemented. When adding tests, create *_test.go files in the appropriate packages.

​
Project Structure

backend/
├── main.go              # Application entry point
├── auth/                # Authentication handlers and JWT logic
│   ├── auth.go         # JWT token generation
│   ├── configs.go      # Session store configuration
│   ├── controller.go   # Business logic (login, registration)
│   └── routes.go       # HTTP handlers
├── configs/            # Configuration and database
│   ├── db.go          # MongoDB connection
│   └── env.go         # Environment variable helpers
├── users/             # User model and operations
│   └── model.go       # User struct and CRUD
├── integrations/      # External API integrations
├── utils/             # Utility functions
├── go.mod             # Go module dependencies
└── Makefile           # Build commands

​
Troubleshooting

​
MongoDB Connection Failed

Ensure MongoDB is running and the MONGODB_URI is correct: 
# Test MongoDB connection
mongosh $MONGODB_URI

​
Port Already in Use

Change the PORT in .env to an available port: 
PORT=8081

​
Module Import Errors

Run go mod tidy to clean up dependencies: 
go mod tidy

​
Next Steps

Authentication

Learn about JWT authentication implementation

Database

Understand MongoDB configuration and operations

User Model

Explore the User model structure and CRUD operations

Build docs developers (and LLMs) love

Get started for freeTalk to us