Architecture

Let’s look about what the cli generate when you run the goframe init command.

Project structure

• bin
  • goframe
  • mjml
• cmd
  • app
  • cli
• config
  • config.go
  • config.yml
  • i18n
• db
  • dbutil
  • migrations
  • seeds
  • migrations.go
  • seeds.go
• internal
  • app
  • mailer
  • provide
  • service
  • task
  • v1handler
  • workflow
• Dockerfile
• docker-compose.yaml
• go.mod
• go.sum

GoFrame follows a clean architecture pattern with dependency injection using Uber’s FX framework. The architecture is designed to be modular, testable, and maintainable, separating concerns into distinct layers.

Detailed explanation

bin/

This directory contains helper binaries for running the GoFrame CLI on your project plus a MJML CLI to compile MJML templates into HTML.

cmd/

This directory contains the entry points for your application. The app folder contains the main application entry point, while the cli folder contains the CLI entry point that includes all generated commands and tasks.

Related : CLI documentation

config/

This directory contains the configuration files for your application. The config.go file is used to load the configuration from the config.yml file.

Related : Configuration documentation

config/i18n/

YAML translations for every locale live here. The bin/goframe i18n commands generate a typed Go helper from these files, allowing for type-safe internationalization throughout your application.

Related : I18n documentation

db/

This directory contains database-related files:

• migrations/ - Database migrations used to create and update the database schema
• seeds/ - Seed files used to populate the database with initial data
• dbutil/ - Database utility functions and helpers
• migrations.go - Lists and manages all migrations
• seeds.go - Lists and manages all seed files

Related : Database documentation

internal/app/module.go

Defines the application dependencies that can be reused across various entrypoints (CLI, HTTP server, etc.). This file registers the application’s structs with Uber’s FX framework for dependency injection.

internal/mailer/

A mailer sends emails using MJML and TXT templates. Each mailer implements an interface so mocks can be used in tests. The mailer contains methods such as SendWelcomeEmail, SendPasswordResetEmail, etc. It integrates with the workflow system for async email sending.

You can generate mailers via the CLI using bin/goframe generate mailer <mailer name> <mail name>.

Related : Mailer documentation

internal/provide/

This directory contains the dependency providers for the application. Each file defines a provider for a specific dependency:

• provide_cache.go - Cache providers and configuration
• provide_db.go - Database connection and configuration
• provide_http.go - HTTP server setup and middleware
• provide_storage.go - File storage providers
• provide_worker.go - Background worker and workflow setup

Since this is code generated by the CLI, you can easily extend it to add your own providers.

internal/service/

This directory contains the service layer, which holds the business logic of the application. Services perform operations on data and interact with repositories and external services.

You can generate services using the CLI with bin/goframe generate service <service name>.

internal/task/

This directory contains CLI tasks that can be run via the command line. Tasks are useful for maintenance operations, data migration, cleanup jobs, etc.

You can generate tasks using the CLI with bin/goframe generate task <task name>.

Related : Tasks documentation

internal/v1handler/

This directory contains the HTTP handlers for the application. The v1 prefix indicates API versioning - you can have multiple versions of your API (v1, v2, etc.).

• registry.go - Registers all handlers with the dependency injection system
• router.go - Defines HTTP routes and maps them to handler methods

You can generate handlers using bin/goframe generate handler <handler name> and add routes with bin/goframe generate route <handler> <method>.

Related : HTTP server documentation

internal/workflow/

This directory contains workflow definitions for long-running, durable processes. Workflows can be paused, resumed, and are fault-tolerant. They’re ideal for complex business processes like order processing, email campaigns, or data pipelines.

• activity/ - Individual workflow activities (atomic operations)
• registry.go - Registers workflows and activities with the worker
• workflow_send_email.go - Example email sending workflow

Uses Temporal as the workflow engine for reliability and scalability.

You can generate workflows using bin/goframe generate workflow <workflow name> <activity name>....

Related : Worker documentation