Encore.dev Template

This is an Encore.dev template.

Prerequisites

Install dependencies:

brew install encoredev/tap/encore

brew install sqlc

brew install just

Create app

Create a local app from this template:

encore app create my-app-name --example=account-management

Run app locally

Run this command from your application's root folder:

encore run

Or use the development workflow with auto-reload:

just dev

Using the API

To test the account creation API:

curl -X POST http://localhost:4000/api/account \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com"
  }'

Local Development Dashboard

While encore run is running, open http://localhost:9400/ to access Encore's local developer dashboard.

Here you can see traces for all requests, view your architecture diagram, and explore API documentation in the Service Catalog.

Architecture

This application includes:

Services

• Account Service (api/account) - Handles user account creation, management, and verification

Database Structure

• Accounts Database - Stores user account information with email verification
• Account Short Codes Database - Manages account short codes for verification
• KYC Identifiers - Stores Know Your Customer verification data (BVN support)

Project Structure

/my-app
├── encore.app              // Encore application configuration
├── Justfile               // Development commands and tasks
├── sqlc.yaml             // SQL code generation configuration
│
├── api/                  // API services
│   └── account/         // Account management service
│       ├── account.go   // Account API endpoints
│       └── encore.gen.go // Generated Encore code
│
├── db/                  // Database layer
│   ├── migrations/      // Database migration files
│   ├── queries/         // SQL queries for sqlc
│   ├── repository/      // Generated repository code
│   └── pkg.go          // Database connections and repositories
│
└── _internal/          // Internal packages
    ├── constants/      // Application constants
    ├── helpers/        // Utility functions
    └── services/       // Business logic services

Development

Add a new service

With Encore.go you can create a new service by creating a regular Go package and then defining at least one API within it. Encore recognizes this as a service, and uses the package name as the service name.

For example, to add a notifications service:

├── api/
│   ├── account/        // existing account service
│   └── notifications/  // new notifications service
│       └── notifications.go

Learn more in the docs: https://encore.dev/docs/go/primitives/services

Create an API endpoint

With Encore.go you can turn a regular Go function into an API endpoint by adding the //encore:api annotation to it. This tells Encore that the function should be exposed as an API endpoint.

For example, the account creation endpoint:

//encore:api public method=POST path=/api/account
func (s *AccountService) CreateAccount(ctx context.Context, p *accounts.CreateAccountParameter) (*CreateAccountResponse, error) {
	account, err := s.accountsService.CreateAccount(ctx, p)
	if err != nil {
		return nil, err
	}

	return &CreateAccountResponse{
		Status:  http.StatusOK,
		Message: "Verification email sent!",
		Data:    account,
	}, nil
}

You can define different access controls using:

• //encore:api public - Public API endpoint
• //encore:api private - Private API only accessible from other services
• //encore:api auth - API that requires authentication

Learn more in the docs: https://encore.dev/docs/go/primitives/defining-apis

Service-to-service API calls

Calling an API endpoint looks like a regular function call with Encore.go. Import the service as a Go package using import "encore.app/api/service-name".

import "encore.app/api/account" // import service

//encore:api public
func MyAPI(ctx context.Context) error {
    resp, err := account.CreateAccount(ctx, &accounts.CreateAccountParameter{
        Email: "user@example.com",
    })
    if err == nil {
        log.Println(resp.Message) // "Verification email sent!"
    }
    return err
}

Learn more in the docs: https://encore.dev/docs/go/primitives/api-calls

Database Management

This template uses PostgreSQL with database migrations and sqlc for type-safe SQL queries.

Database Configuration

Databases are configured in db/pkg.go:

var (
    AccountsPool = sqldb.Driver[*pgxpool.Pool](sqldb.NewDatabase("accounts", sqldb.DatabaseConfig{Migrations: "migrations"}))
    AccountShortCodesPool = sqldb.Driver[*pgxpool.Pool](sqldb.NewDatabase("account_short_codes", sqldb.DatabaseConfig{Migrations: "migrations"}))
)

Adding Migrations

Create migration files in db/migrations/ directory:

-- 3_add_new_feature.up.sql
ALTER TABLE account ADD COLUMN phone_number TEXT;

Apply migrations by restarting your app with encore run or just dev.

Working with SQL Queries

1. Add SQL queries to db/queries/
2. Run sqlc generate or just sql-gen to generate Go code
3. Use the generated repository methods in your services

Available Commands

This project uses just for task management:

just dev          # Start development server with auto-reload
just sql-gen      # Generate SQL code from queries
just db-shell     # Open database shell
just db-reset     # Reset all databases
just test         # Run tests
just test-coverage # Run tests with coverage
just clean        # Clean generated files

Learn more

Explore additional Encore.go features:

• Cron jobs
• Pub/Sub
• Object Storage
• Secrets
• Authentication handlers
• Middleware

Deployment

Self-hosting

See the self-hosting instructions for how to use encore build docker to create a Docker image and configure it.

Encore Cloud Platform

Deploy your application to a free staging environment in Encore's development cloud using git push encore:

git add -A .
git commit -m 'Deploy account management system'
git push encore

You can also open your app in the Cloud Dashboard to integrate with GitHub, or connect your AWS/GCP account for automatic cloud deployments.

Link to GitHub

Follow these steps to link your app to GitHub:

1. Create a GitHub repo, commit and push the app.
2. Open your app in the Cloud Dashboard.
3. Go to Settings ➔ GitHub and click on Link app to GitHub to link your app to GitHub and select the repo you just created.
4. To configure Encore to automatically trigger deploys when you push to a specific branch name, go to the Overview page for your intended environment. Click on Settings and then in the section Branch Push configure the Branch name and hit Save.
5. Commit and push a change to GitHub to trigger a deploy.

Learn more in the docs

Testing

Run all tests:

encore test ./...

Or use the just command:

just test

Run tests with coverage:

just test-coverage