DEV Community: Jorge Gomez

FRD Orchestration with MCP: Deterministic Context Control for Agents (No Drift)

Jorge Gomez — Wed, 31 Dec 2025 18:34:57 +0000

`Some time ago, I wrote this article, explaining the value of orchestrating multiple Feature Requirement Documents (FRDs) to keep full control over building a NestJS boilerplate from scratch, step by step.

FRD-00: orchestration
FRD-01: skeleton
FRD-02: ORM + migrations
FRD-03: auth + JWT
FRD-04: unit testing

It worked, but a classic problem showed up: when FRDs live as “loose” files in the workspace, the agent can read the wrong .md, mix phases, or cache the wrong context.

Before: FRDs as files inside a folder → the agent might read the wrong document / mix phases / cache context.
Now: an MCP tool get_frd("00".."04") that returns the correct FRD by ID → phase-controlled delegation, less drift, and more repeatability.

Context: previous approach (file-based context)

In the earlier article, I showed the benefits of using Feature Requirement Documents (FRDs) to guide an agent through building a boilerplate. It worked… but it had one major weakness: the agent relied on “correctly reading” files inside a folder.

The workspace looked like this:

The initial input I gave the agent was:
`

folder name: `api-products`  
 - FRD-00-master-orchestration.md  
 - FRD-01-boilerplate-core-products.md  
 - FRD-02-products-database.md  
 - FRD-03-auth-security.md  
 - FRD-04-unit-testing.md  
 - Start the orchestration..

Even though FRD-00 defines the order and delegates each phase, the weak point was still there: file selection inside the workspace.

The real problem: an ambiguous context “selector”

When an agent works with file-based context from the workspace, the typical failures are:

Reading the wrong .md.
Mixing phases (skipping steps).
Running commands outside the target folder.

In short: execution stops being reproducible because a critical part depends on a non-deterministic step.

Solution: deterministic retrieval via MCP

To eliminate that weak point, I moved FRD reading to a deterministic mechanism using Model Context Protocol (MCP).

What is MCP? Model Context Protocol (MCP) is a protocol that lets you expose tools (functions) to an agent/IDE so it can request information in a controlled way, instead of “guessing” by reading workspace files.

Instead of “searching for files,” the agent requests exactly the document it needs through a tool:

get_frd("00") → main orchestration
get_frd("01") → phase 1
get_frd("02") → phase 2
get_frd("03") → phase 3
get_frd("04") → phase 4

Python tool implementation

Result: orchestration no longer depends on the agent’s “file picking.” At each phase, the agent requests the correct FRD, in the correct order.

Why this improves orchestration (and it’s not just “more organization”)

1) Less drift

The agent doesn’t “infer” which file to read: it is given the exact document.

2) More repeatability

Two separate runs tend to produce the same outcome because the spec input is stable.

3) Phase-controlled delegation

The active phase determines which FRD is exposed. This even allows adding policies such as:

“You can’t request FRD-03 unless FRD-02 is completed.”
“Always request FRD-00 before any other.”

Demo (operational evidence)

In VSCode, open the MCP Servers view and verify that frd-orchestrator is active.

Checking the local server works thanks to this configuration.

Note: on my machine, uv is located at /Users/jorgegomez/.local/bin/uv. On yours, it may vary.

// .vscode/mcp.json
{
  "servers": {
    "frd-orchestrator": {
      "type": "stdio",
      "command": "/Users/jorgegomez/.local/bin/uv",
      "args": ["run", "main.py"]
    }
  }
}

`
and it automatically enables the local MCP server.

When the server starts, we can see in the VSCode console that our MCP server is running.

In practice, it looks like this: each phase triggers get_frd("0X"), and the server responds by reading the exact file from disk.

In the MCP server logs, you can see how the agent requests FRDs by ID at the right moment:

[FRD-Orchestrator] get_frd tool requested with frd_id=02  
Reading FRD from disk: .../frd/FRD-02-products-database.md

[FRD-Orchestrator] get_frd tool requested with frd_id=03  
Reading FRD from disk: .../frd/FRD-03-auth-security.md

[FRD-Orchestrator] get_frd tool requested with frd_id=04  
Reading FRD from disk: .../frd/FRD-04-unit-testing.md

`
This is exactly what we’re aiming for: explicit tool calls instead of “free-form” workspace reading.

With MCP, context stops being “workspace exploration” and becomes “controlled retrieval.”

That reduces errors, speeds up orchestration, and makes the flow more reproducible.

It may not look like much, but here’s the real benefit: this scales in enterprise environments. With MCP, AI stops being “just a chat” and becomes a controlled component to automate tasks, flows, and workflows aligned with each company’s business logic. That’s where developers should be heading today: AI + deterministic tools + reproducible processes.

Github repo

If you made it this far, I’d love for you to review this approach and share your thoughts. I’m fully open to feedback, criticism, and suggestions for improvement—both on the FRD design and the MCP implementation. If you spot anything that could be cleaner, safer, or more reproducible, please let me know in the comments.

🚀 How I Used AI, FRDs, Claude Sonnet, Windsurf, and Antigravity to Orchestrate a Complete Backend Without Chaos

Jorge Gomez — Fri, 28 Nov 2025 14:24:32 +0000

A Reproducible Methodology for Generating Real, Clean, and Scalable Software Using LLM Agents Orchestrated Through Formal FRD Documents

Introduction

Over the past few weeks, I’ve been applying a development approach based on FRDs (Functional Requirements Documents) orchestrated with the support of Artificial Intelligence to build modern, clean, and scalable backends. This method allowed me to generate a complete backend—from CRUD, database layer, JWT authentication, migrations, and unit testing—without chaos, without improvisation, and with clean code from the very first commit.

Although FRDs are a traditional standard widely used in software engineering, what’s truly interesting here is not the FRD concept itself, but how FRDs are combined with LLM agents to create a deterministic build process.

This approach aligns with modern techniques such as LLM Orchestration, Task Graphs, and Agentic Pipelines, which are becoming mainstream in tools like Windsurf, Cursor, Claude Sonnet, and VSCode Agents.

One key insight I found early on was that I initially started with a massive FRD—a single document describing all phases (boilerplate, database, authentication, testing, etc.). Even though the document was detailed, two real problems quickly emerged:

LLMs had to process too much information in a single context window, increasing reasoning load and causing the agent to drift, forget steps, or ask redundant questions.
The process became slow because the model entered loops of “confirmation,” uncertainty, ambiguity, and frequent re-validation.

This led me to investigate a more scalable approach: splitting the project into multiple small FRDs, each responsible for a specific phase, and introducing a Master FRD-00 responsible for orchestrating them in the correct order.

With this structure:

The LLM no longer needs to parse a giant document
Each stage has a short, precise FRD
The Master FRD controls the entire execution pipeline
The agent stops asking “what’s next” and simply executes
Adding new features becomes safer and easier because each one lives in its own FRD without interfering with others

What Is FRD-Based Orchestration?

FRDs define:

What needs to be built
In what order
What criteria must be satisfied
Which steps are mandatory
What behaviors the AI must validate
What acceptance conditions each phase must pass

The key insight is that you’re not only describing features, you’re also defining the construction process itself, ensuring accuracy, repeatability, and zero improvisation.

📘 Connection to Existing Practices

FRD-based orchestration does not try to reinvent methodologies—it integrates formal, well-known practices with the new wave of AI-assisted development.

This method incorporates ideas from:

LLM-driven Development Workflows
Prompt Chaining
Task Graph Execution
Reproducible Pipelines
Specification-Driven Engineering

The contribution here lies in how the process is structured, not in the FRD concept itself.

FRD-00: The Orchestration Controller

This master document defines:

Required phases
Clear dependencies
Agent behavior
Validation rules per stage
Strict conditions to advance or stop
Success criteria for each phase

It acts as the logical pipeline that ensures the project can be executed by AI without deviations.

🔗 Ruta

🚀 How Orchestration Actually Begins

Before starting any phase, I execute this initial instruction so the AI loads all FRDs and understands the execution order:

@FRD-00-master-orchestration.md
@FRD-01-boilerplate-core-products.md
@FRD-02-products-database.md
@FRD-03-auth-security.md
@FRD-04-unit-testing.md 

folder name: api-products

FRD-00-master-orchestration.md
FRD-01-boilerplate-core-products.md
FRD-02-products-persistence-typeorm.md
FRD-03-unit-testing.md

Start the orchestration.

Why Is This Critical?

Ensures the agent follows the correct order
Enforces FRD-00 as the master controller
Reduces context overload
Prevents unnecessary loops or clarifying questions
Makes the process reproducible across any AI editor: Windsurf, Antigravity, Cursor, Sonnet, VSCode Agents, etc.

General Project Architecture

The final result was a NestJS backend with:

🧩 Included Modules

Auth (JWT + bcrypt + Passport)
Users (registration, login, hashing)
Products (CRUD with validation)
Centralized config
SQLite + TypeORM + migrations
Unit testing (33 tests)

📁 Final Structure

api-products/
├── src/
│   ├── auth/
│   ├── products/
│   ├── users/
│   ├── config/
│   └── main.ts
├── migrations/
├── README.md
└── package.json

🔥 Phase 1 — Boilerplate + In-Memory CRUD

Project created using nest new
Swagger enabled
Global validation pipes
In-memory CRUD
DTOs with class-validator
Mandatory JSDoc

export class CreateProductDto {
  @IsString()
  name: string;

  @IsBoolean()
  isPremium: boolean;

  @IsNumber()
  price: number;
}

🔗 Ruta

🗄️ Phase 2 — Database + TypeORM

TypeORM integration
Migrations
ProductRepository
Real persistence using SQLite

@Entity()
export class Product {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  name: string;

  @Column()
  isPremium: boolean;

  @Column('float')
  price: number;
}

🔗 Ruta

🔐 Phase 3 — JWT Authentication

UsersService + repository
bcrypt hashing
LocalStrategy + JwtStrategy
JwtAuthGuard
Swagger Bearer Auth

  async login(loginDto: LoginDto): Promise<{ accessToken: string }> {
    const user = await this.usersService.validateCredentials(loginDto.email, loginDto.password);

    if (!user) {
      throw new UnauthorizedException('Invalid credentials');
    }

    const payload = { email: user.email, sub: user.id };
    const accessToken = this.jwtService.sign(payload);

    return { accessToken };
  }

🔗 Ruta

🧪 Phase 4 — Unit Testing

6 test suites
33 tests
Clean mocks
No real database

  describe('login', () => {
    it('should login successfully and return access token', async () => {
      const loginDto: LoginDto = {
        email: 'test@example.com',
        password: 'password123',
      };
      const accessToken = 'jwt-token';
      mockUsersService.validateCredentials.mockResolvedValue(mockUser);
      mockJwtService.sign.mockReturnValue(accessToken);

      const result = await service.login(loginDto);

      expect(result).toEqual({ accessToken });
      expect(usersService.validateCredentials).toHaveBeenCalledWith(loginDto.email, loginDto.password);
      expect(jwtService.sign).toHaveBeenCalledWith({ email: mockUser.email, sub: mockUser.id });
    });

    it('should throw UnauthorizedException for invalid credentials', async () => {
      const loginDto: LoginDto = {
        email: 'test@example.com',
        password: 'wrongpassword',
      };
      mockUsersService.validateCredentials.mockResolvedValue(null);

      await expect(service.login(loginDto)).rejects.toThrow(UnauthorizedException);
      expect(usersService.validateCredentials).toHaveBeenCalledWith(loginDto.email, loginDto.password);
    });
  });

🔗 Ruta

📊 Final Results

All 33 tests passing
Migrations working
JWT fully functional
CRUD operational
Consistent architecture

🖼️ Visual Evidence

(Gallery with screenshots from Windsurf, Antigravity, and Claude Sonnet)

🧠 Why This Matters in the AI Era

AI needs structure
Enables end-to-end project execution
Reinforces best practices in LLM-assisted development workflows.
Reproducible, scalable, modular

🧭 Conclusion

FRD Orchestration is not merely an operational technique—it is a way of structuring collaboration between humans and AI models to produce reproducible, stable, and scalable software.

This method enhances—not replaces—the developer.

📂 Official Repository with FRDs + Full Backend

🚀 Cómo Usé IA, FRDs, Claude Sonnet, Windsurf y Antigravity para Orquestar un Backend Completo Sin Caos

Jorge Gomez — Fri, 28 Nov 2025 03:57:18 +0000

Una metodología reproducible para generar software real, limpio y escalable usando agentes LLM orquestados por documentos FRD formales.

Introducción

En estas últimas semanas he estado aplicando un enfoque de desarrollo basado en FRDs (Functional Requirements Documents) orquestados con apoyo de Inteligencia Artificial para construir backends modernos, limpios y escalables. Este método me permitió crear un backend completo —con CRUD, base de datos, autenticación JWT, migraciones y pruebas unitarias— sin caos, sin improvisación y con código limpio desde el primer commit.

Aunque los FRDs son un estándar tradicional ampliamente usado en ingeniería de software, lo verdaderamente interesante aquí no es el concepto del FRD en sí, sino cómo se combinan con agentes LLM para crear un proceso determinístico de construcción.

Este enfoque se alinea con técnicas modernas de LLM Orchestration, Task Graphs y Agentic Pipelines, que están siendo adoptadas en herramientas como Windsurf, Cursor, Claude Sonnet y VSCode Agents.

Algo que noté durante este proceso es que comencé usando un FRD gigante, un documento único donde describía todas las fases (boilerplate, base de datos, autenticación, pruebas, etc.). Aunque el documento era muy detallado, pronto aparecieron dos problemas reales:

Los modelos de IA tenían que analizar demasiada información en una sola ventana de contexto, lo cual aumentaba la carga de razonamiento y hacía que el agente se desviara, olvidara pasos o repitiera preguntas innecesarias.
El proceso se volvía lento porque la IA entraba en ciclos de “confirmación”, dudas, ambigüedades y revalidaciones constantes.

Esto me llevó a investigar un enfoque más escalable: separar el proyecto en múltiples FRDs pequeños, cada uno responsable de una fase específica, y crear un FRD-00 Maestro que los orquestara en el orden correcto.

Con esa estructura:

La IA ya no necesita analizar un documento gigantesco.
Cada fase tiene un FRD corto y preciso.
El FRD Maestro controla el flujo completo como un pipeline.
El agente deja de preguntar “qué sigue” y simplemente ejecuta.
Agregar nuevas features en el futuro es más sencillo y seguro, porque cada una vive en su propio FRD sin interferir con las demás.

¿Qué es la Orquestación por FRDs?

Los FRDs definen:

Qué debe hacerse
En qué orden
Qué criterios deben cumplirse
Qué pasos son obligatorios
Qué comportamientos debe validar la IA
Qué condiciones de aceptación debe pasar cada fase

La clave está en que no solo describes la funcionalidad, sino que defines el proceso de construcción, asegurando precisión, repetibilidad y cero improvisación.

📘 Relación con prácticas existentes

La orquestación por FRDs no pretende reinventar metodologías: más bien integra prácticas formales ya conocidas con la nueva ola de desarrollo asistido por IA.

Este método toma elementos de:

LLM-driven Development Workflows
Prompt Chaining
Task Graph Execution
Reproducible Pipelines
Specification-Driven Engineering

La contribución aquí es cómo se estructura el proceso, no el concepto del FRD en sí.

FRD-00: El "Controlador de Orquestación"

Este documento maestro dicta:

Fases obligatorias
Dependencias claras
Comportamiento del agente
Validaciones en cada etapa
Reglas estrictas para avanzar o detenerse
Criterios de éxito por fase

Es el pipeline lógico que permite que el proyecto sea ejecutado por IA sin desviaciones.

🔗 Ruta

🚀 ¿Cómo inicia realmente la orquestación?

Antes de empezar las fases, ejecuto esta instrucción inicial para que la IA cargue todos los FRDs y comprenda el orden de ejecución:

@FRD-00-master-orchestration.md
@FRD-01-boilerplate-core-products.md
@FRD-02-products-database.md
@FRD-03-auth-security.md
@FRD-04-unit-testing.md

nombre de carpeta: api-products

FRD-00-master-orchestration.md
FRD-01-boilerplate-core-products.md
FRD-02-products-persistence-typeorm.md
FRD-03-unit-testing.md

Inicia la orquestación.

¿Por qué esto es crítico?

Garantiza que el agente siga el orden correcto
Asegura que el FRD-00 actúe como director maestro
Reduce carga de contexto
Evita loops o preguntas innecesarias
Permite reproducibilidad en cualquier editor IA: Windsurf, Antigravity, Cursor, Sonnet, VSCode Agents, etc.

Arquitectura General del Proyecto

El resultado final fue un backend NestJS con:

🧩 Módulos incluidos

Auth (JWT + bcrypt + Passport)
Users (registro, login, hashing)
Products (CRUD con validación)
Config centralizado
SQLite + TypeORM + migraciones
Pruebas unitarias (33 tests)

📁 Estructura final

api-products/
├── src/
│   ├── auth/
│   ├── products/
│   ├── users/
│   ├── config/
│   └── main.ts
├── migrations/
├── README.md
└── package.json

🔥 Fase 1 — Boilerplate + CRUD en memoria

Proyecto creado con nest new
Swagger activado
Validaciones globales
CRUD in-memory
DTOs con class-validator
JSDoc obligatorio

export class CreateProductDto {
  @IsString()
  name: string;

  @IsBoolean()
  isPremium: boolean;

  @IsNumber()
  price: number;
}

`
🔗 Ruta

🗄️ Fase 2 — Base de Datos + TypeORM

Integración TypeORM
Migraciones
ProductRepository
Persistencia real con SQLite

@Entity()
export class Product {
  @PrimaryGeneratedColumn('uuid')
  id: string;

  @Column()
  name: string;

  @Column()
  isPremium: boolean;

  @Column('float')
  price: number;
}

`
🔗 Ruta

🔐 Fase 3 — Autenticación JWT

UsersService + repositorio
Hashing con bcrypt
LocalStrategy + JwtStrategy
JwtAuthGuard
Swagger BearerAuth

  async login(loginDto: LoginDto): Promise<{ accessToken: string }> {
    const user = await this.usersService.validateCredentials(loginDto.email, loginDto.password);

    if (!user) {
      throw new UnauthorizedException('Invalid credentials');
    }

    const payload = { email: user.email, sub: user.id };
    const accessToken = this.jwtService.sign(payload);

    return { accessToken };
  }

🔗 Ruta

🧪 Fase 4 — Pruebas Unitarias

6 test suites
33 pruebas
Mocks limpios
Sin BD real

  describe('login', () => {
    it('should login successfully and return access token', async () => {
      const loginDto: LoginDto = {
        email: 'test@example.com',
        password: 'password123',
      };
      const accessToken = 'jwt-token';
      mockUsersService.validateCredentials.mockResolvedValue(mockUser);
      mockJwtService.sign.mockReturnValue(accessToken);

      const result = await service.login(loginDto);

      expect(result).toEqual({ accessToken });
      expect(usersService.validateCredentials).toHaveBeenCalledWith(loginDto.email, loginDto.password);
      expect(jwtService.sign).toHaveBeenCalledWith({ email: mockUser.email, sub: mockUser.id });
    });

    it('should throw UnauthorizedException for invalid credentials', async () => {
      const loginDto: LoginDto = {
        email: 'test@example.com',
        password: 'wrongpassword',
      };
      mockUsersService.validateCredentials.mockResolvedValue(null);

      await expect(service.login(loginDto)).rejects.toThrow(UnauthorizedException);
      expect(usersService.validateCredentials).toHaveBeenCalledWith(loginDto.email, loginDto.password);
    });
  });

🔗 Ruta

📊 Resultados Finales

33 pruebas exitosas
Migraciones correctas
JWT funcionando
CRUD operativo
Arquitectura consistente

🖼️ Visual Evidence

(Gallery with screenshots from Windsurf, Antigravity, and Claude Sonnet)

🧠 Importancia en la era de la IA

La IA necesita estructura
Permite la ejecución de proyectos de extremo a extremo
Refuerza buenas prácticas en flujos asistidos por modelos LLM
Es reproducible, escalable y modular

🧭 Conclusión

La Orquestación por FRDs no es simplemente una técnica operativa: es una forma de estructurar la colaboración entre humanos y modelos de IA para producir software reproducible, estable y escalable.

Este método potencia —no reemplaza— al desarrollador.

📂 Repositorio oficial con FRDs + Backend completo

Descubriendo la Potencia de Go: Backend Inicial con buenas practicas

Jorge Gomez — Sat, 06 Apr 2024 03:30:23 +0000

En el vasto universo de la programación, cada lenguaje tiene su brillo único, su propósito especial. Entre estos, Go (o Golang) destaca por su simplicidad, eficiencia y capacidad para manejar concurrencia. Como desarrollador apasionado por aprender y explorar, decidí embarcarme en un viaje: crear un proyecto desde cero utilizando Go. Este artículo no solo subraya la importancia de Go en el desarrollo moderno de software, sino que también comparte mi experiencia construyendo una aplicación estructurada y funcional, paso a paso.

¿Por Qué Go?
Go fue diseñado en Google para mejorar la productividad en la programación en un entorno de sistemas complejos. Su sintaxis clara y su sistema de tipos, junto con el manejo nativo de la concurrencia mediante goroutines, lo hacen excepcionalmente potente para el desarrollo de servidores web, servicios en tiempo real y herramientas de productividad.

Mi fuerte esta con NodeJS usando NestJS, en los cuales he aprendido a lo largo de mi carrera, buenas practicas aplicando:

Arquitectura de 3 capas Repositorios, Servicios y Controladores
Manejo de Errores
Configuracion de base de datos
Migraciones
Organizacion inicial de configuraciones iniciales
Variables de Entorno

Quise llevar todas mis experiencias y moldearlo en un backend Go, con una estructura inicial de arquitectura, por lo tanto asi comence:

Go trabaja con un archivo principal llamado main.go, en el cual todas las instrucciones que iniciemos comenzaran en este lugar

package main

import "fmt"

func main() {
    fmt.Println("Hello world")
}

Este es el clasico hola mundo para todos, pero lo dejo para que sepas como debe de iniciar , puede tener otro nombre que ustedes quieran , pero lo importante es que se dicho archivo debe de iniciarse con la instrucción:

go run main.go

Antes de ponernos manos a la obra, debemos tener claro nuestra estructura de carpetas para nuestro backend, esta estructura inicial puede permitirnos tener una buena organización en la distribución de responsabilidades en nuestro backend lo cual sera el siguiente

/api-golang
---/bootstrap - Configuración del contenedor de inyección de dependencias
---/config - Gestión de configuración centralizada
---/controller - Controladores HTTP
---/database - Conexión y configuración de la base
de datos
---/dto - Definicion de DTO para los
controladores
---/migrations - Migraciones de base de datos
---/errors - Definiciones de errores personalizados
---/models - Modelos de datos
---/repositories - Acceso y manipulación de la base de datos
---/services - Lógica de negocio
---main.go - Punto de entrada de la aplicación
---.env - Variables de entorno

Config

En esta carpeta tendremos un archivo llamado config.go, en el cual tendremos configurado las variables de entorno necesarias para usar en cualquier parte de nuestro backend usando la libreria github.com/joho/godotenv

package config

import (
    "log"
    "os"

    "github.com/joho/godotenv"
)

type Config struct {
    DBUser     string
    DBPass     string
    DBHost     string
    DBPort     string
    DBName     string
    DBSSLMode  string
    ServerPort string
}

func LoadConfig() Config {
    err := godotenv.Load()
    if err != nil {
        log.Println("Warning: No .env file found")
    }

    return Config{
        DBUser:     os.Getenv("DB_USER"),
        DBPass:     os.Getenv("DB_PASSWORD"),
        DBHost:     os.Getenv("DB_HOST"),
        DBPort:     os.Getenv("DB_PORT"),
        DBName:     os.Getenv("DB_NAME"),
        DBSSLMode:  os.Getenv("DB_SSLMODE"),
        ServerPort: os.Getenv("SERVER_PORT"),
    }
}

el archivo .env debe de tener lo siguiente

DB_USER=postgres
DB_PASSWORD=123456
DB_HOST=localhost
DB_NAME=golang
DB_PORT=5432
DB_SSLMODE=disable

Database

En esta carpeta tenemos el archivo db.go, el cual sera encargado de tener preparado nuestra conexión a la base de datos tomando en cuenta por la importacion "api-golang/config", aplicando el struct de config.go en func ConnectDatabase(cfg config.Config), podemos acceder a las variables de entorno necesarias para la configurar las credenciales de la base de datos

db.go

package database

import (
    "api-golang/config"
    "fmt"
    "log"

    "gorm.io/driver/postgres"
    "gorm.io/gorm"
)

func ConnectDatabase(cfg config.Config) (*gorm.DB, error) {
    dsn := fmt.Sprintf("postgres://%s:%s@%s:%s/%s?sslmode=%s",
        cfg.DBUser, cfg.DBPass, cfg.DBHost, cfg.DBPort, cfg.DBName, cfg.DBSSLMode)

    database, err := gorm.Open(postgres.Open(dsn), &gorm.Config{})
    if err != nil {
        log.Fatalf("Failed to connect to database: %v", err)
    }
    return database, nil
}

Migrations

Es muy importante tener en nuestra estructura , un arranque inicial de una base de datos, por lo tanto por medio de la libreria github.com/golang-migrate/migrate/v4, tendremos las bondades de correr migraciones nuevas o modificaciones las cuales definiremos en archivos .sql, el archivo es

/migrations/migrations.go

package migrations

import (
    "log"
    "path/filepath"
    "runtime"

    "github.com/golang-migrate/migrate/v4"
    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func Migrate(dsn string) {
    _, b, _, _ := runtime.Caller(0)
    dir := filepath.Join(filepath.Dir(b), "migrations")

    m, err := migrate.New("file://"+dir, dsn)
    if err != nil {
        log.Fatalf("Error while creating migrate instance: %v", err)
    }

    // Apply all the available migrations
    if err := m.Up(); err != nil && err != migrate.ErrNoChange {
        log.Fatalf("Error while applying migrations: %v", err)
    }

    log.Println("Migrations applied successfully!")
}

Para poder correr las migraciones por comandos cli, podemos usar un archivo Makefile, el cual es una forma de correr tareas personalizadas para GO, el cual se define asi

migrateup:
    migrate -path ./migrations -database "postgres://postgres:123456@localhost:5432/golang?sslmode=disable" up

migratedown:
    migrate -path ./migrations -database "postgres://postgres:123456@localhost:5432/golang?sslmode=disable" down

y para correr el comando por consola make migrateup

al correr el comando puedes iniciar los archivos default que tengas de .sql como por ejemplo

/migrations/1_create_products_table.up.sql

-- +migrate Up
CREATE TABLE IF NOT EXISTS products (
    id SERIAL PRIMARY KEY,
    nombre VARCHAR(100) NOT NULL,
    precio NUMERIC NOT NULL
);

/migrations/1_create_products_table.down.sql

-- +migrate Down
DROP TABLE IF EXISTS products;

Puedes crear todas las migraciones que necesites, la base de datos creara una tabla de control a fin de tener el seguimiento de las migraciones aplicadas.

Errors

Siempre es importante tener un archivo central , por el cual podemos contrar los errores por medio de un mensaje generico, el siguiente archivo tiene la configuracion inicial a usar para los errores

/errors/errors.go

package errors

// ErrorType enumerates the known error types for the application
type ErrorType int

const (
    DatabaseError ErrorType = iota + 1
    ValidationError
    InternalError
)

// AppError represents an error with an associated type and message
type AppError struct {
    Type    ErrorType
    Message string
}

func (e *AppError) Error() string {
    return e.Message
}

// New crea un nuevo AppError
func New(typ ErrorType, msg string) error {
    return &AppError{
        Type:    typ,
        Message: msg,
    }
}

Repositorio

Aqui configuramos toda la logica relacionada a las consultas a la base de datos, puede ser de modo generico usando el ORM o queryBuilder, y ademas de consultas personalizadas, pero lo importante, es que la responsabilidad de manipular la base de datos solo estara en este sitio, en este caso tomando en cuenta una tabla de product, podemos tener el siguiente archivo

/repositories/product.go

package repositories

import (
    "api-golang/models"

    "gorm.io/gorm"
)

type ProductRepository interface {
    FindAll() ([]models.Product, error)
    Save(producto models.Product) (models.Product, error)
}

type productoRepository struct {
    db *gorm.DB
}

func NewProductoRepository(db *gorm.DB) ProductRepository {
    return &productoRepository{db: db}
}

func (r *productoRepository) FindAll() ([]models.Product, error) {
    var productos []models.Product
    result := r.db.Find(&productos)
    return productos, result.Error
}

func (r *productoRepository) Save(producto models.Product) (models.Product, error) {
    result := r.db.Create(&producto)
    return producto, result.Error
}

Este repositorio en Go sirve como una capa de abstracción entre la lógica de negocio de nuestra aplicación y las operaciones de base de datos específicas para Product. Utiliza el ORM Gorm, una popular biblioteca de mapeo objeto-relacional en Go, que facilita la interacción con la base de datos utilizando Go structs en lugar de consultas SQL directas, en el siguiente bloque

// Struct a el ORM Gorm a fin de usar las bondades del orm
type productoRepository struct {
    db *gorm.DB
}

productoRepository contiene un solo campo, db, que es un puntero a una instancia de gorm.DB. Este campo db representa una sesión de base de datos con Gorm, que se utiliza para realizar operaciones de base de datos (consultas, inserciones, actualizaciones, etc.) relacionadas con productos.

Al ser un puntero (*gorm.DB), db mantiene una referencia a la instancia de la base de datos, lo cual significa que los cambios que se realicen afectaran cualquier lado del backend, lo cual es crucial para mantener la actualizada la base de datos y al usarlo en ls siguiente funcion

func (r *productoRepository) FindAll() ([]models.Product, error) {
    var productos []models.Product
    result := r.db.Find(&productos)
    return productos, result.Error
}

r *productoRepository tiene la asociacion a las bondades del orm usando r.db.Find, ademas de usarlo con tras funciones basicas del orm para registrar, eliminar etc.

Service

En esta capa tenemos la logica del negocio, el cual se llamara

/services/product.go

package services

import (
    "api-golang/errors"
    "api-golang/models"
    "api-golang/repositories"
)

type ProductService interface {
    GetAllProductos() ([]models.Product, error)
    CreateProduct(producto models.Product) (models.Product, error)
}

type productoService struct {
    repository repositories.ProductRepository
}

func NewProductoService(repository repositories.ProductRepository) ProductService {
    return &productoService{repository: repository}
}

func (s *productoService) GetAllProductos() ([]models.Product, error) {
    res, err := s.repository.FindAll()
    if err != nil {
        return []models.Product{}, errors.New(errors.DatabaseError, "Error find all product: "+err.Error())
    }
    return res, nil
}

func (s *productoService) CreateProduct(producto models.Product) (models.Product, error) {
    // Intenta guardar el producto y maneja tanto el producto guardado como el error
    savedProduct, err := s.repository.Save(producto)
    if err != nil {
        // Aquí manejas el error, creando un nuevo AppError con tipo DatabaseError
        return models.Product{}, errors.New(errors.DatabaseError, "Error saving product: "+err.Error())
    }
    // Si no hay error, devuelve el producto guardado y nil para el error
    return savedProduct, nil
}

En este archivo aplicamos nuevamente una instancia en

type productoService struct {
   repository repositories.ProductRepository
}

en el cual instanciamos la interfaz de ProductRepository a fin de acceder a las funciones definidas como FindAll en el siguiente codigo:

func (s *productoService) GetAllProductos() ([]models.Product, error) {
    res, err := s.repository.FindAll()
    if err != nil {
        return []models.Product{}, errors.New(errors.DatabaseError, "Error find all product: "+err.Error())
    }
    return res, nil
}

En esta función accedemos a todos los productos , en el caso de que se tenga un error , se enviarn a la funcion DatabaseError del archivo definido mas arriba en /errors/errors.go

Controller

En esta capa tenemos el control de las solicitudes HTTP, en este lugar debemos validar lo que recibimos por payload o por params a fin de tener seguridad en el procesamiento de los datos, ademas se define la validacion de los datos usando DTO(Data Transfer Object) a fin de tener seguridad de los datos de entrada, para este caso se usaran solo dos endpoints los cuales haran el registro y obtencion de productos

/controller/product.go

package controller

import (
    "api-golang/dto"
    "api-golang/models"
    "api-golang/services"
    "encoding/json"
    "net/http"
)

type ProductController struct {
    Service services.ProductService
}

func NewProductController(service services.ProductService) *ProductController {
    return &ProductController{Service: service}
}

func (c *ProductController) GetProducts(w http.ResponseWriter, r *http.Request) {
    productos, err := c.Service.GetAllProductos()
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(productos)
}

func (c *ProductController) CreateProduct(w http.ResponseWriter, r *http.Request) {
    var productDTO dto.ProductCreateDTO
    if err := json.NewDecoder(r.Body).Decode(&productDTO); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    // DTO Validation
    if validationErrors := productDTO.Validate(); validationErrors != nil {
        http.Error(w, "Validation failed", http.StatusBadRequest)
        return
    }

    product := models.Product{Nombre: productDTO.Nombre, Precio: productDTO.Precio}
    savedProduct, err := c.Service.CreateProduct(product)
    if err != nil {
        http.Error(w, err.Error(), http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(savedProduct)
}

Por medio de

type ProductController struct { Service services.ProductService }

Accedemos a la instancia de la interfaz ProductService a fin de acceder a las funciones del servicio como por ejemplo c.Service.CreateProduct, para tener el response final json.NewEncoder(w).Encode(producto) realiza la serializacion a JSON por medio de json.NewEncoder(w)

En el bloque

// DTO Validation if validationErrors := productDTO.Validate(); validationErrors != nil { http.Error(w, "Validation failed", http.StatusBadRequest) return }

Se realiza la validation del DTO por medio del archivo

/dto/dto.go

package dto

import "github.com/go-playground/validator/v10"

type ProductCreateDTO struct {
    Nombre string  `json:"name" validate:"required,min=2,max=100"`
    Precio float64 `json:"price" validate:"required,gt=0"`
}

func (p *ProductCreateDTO) Validate() []*validator.FieldError {
    validate := validator.New()
    err := validate.Struct(p)
    if err != nil {
        var fieldErrors []*validator.FieldError

        if ve, ok := err.(validator.ValidationErrors); ok {
            for _, fe := range ve {
                fieldError := fe
                fieldErrors = append(fieldErrors, &fieldError)
            }
            return fieldErrors
        }
    }
    return nil
}

type ProductCreateDTO struct { Nombre stringjson:"name" validate:"required,min=2,max=100"Precio float64json:"price" validate:"required,gt=0"}

Usando una librera de validacion de datos github.com/go-playground/validator/v10, especificamos en los campos de la entidad Product por medio del struct ProductCreateDTO, los campos a validar con casos regulares de DTO como campos requeridos y tipos de datos

Bootstrap

En este archivo tendremos centralizado nuestros repositorios , servicios y controladores , ademas de encender la conexión de la base de datos, el cual sera el siguiente

/bootstrap/bootstrap.go

package bootstrap

import (
    "api-golang/config"
    "api-golang/controller"
    "api-golang/database"
    "api-golang/repositories"
    "api-golang/services"
    "log"

    "go.uber.org/dig"
    "gorm.io/gorm"
)

func BuildContainer(cfg config.Config) *dig.Container {
    container := dig.New()

    // Database Connection Registration
    container.Provide(func() (*gorm.DB, error) {
        return database.ConnectDatabase(cfg)
    })

    // Repositories
    if err := container.Provide(repositories.NewProductoRepository); err != nil {
        log.Fatalf("Failed to provide product repository: %v", err)
    }

    // Services
    if err := container.Provide(services.NewProductoService); err != nil {
        log.Fatalf("Failed to provide product service: %v", err)
    }

    // Controller
    if err := container.Provide(controller.NewProductController); err != nil {
        log.Fatalf("Failed to provide product controller: %v", err)
    }

    return container
}

Es importante tener en un solo lugar, todas las incializaciones de los archivos a usar, si se requiere inicializar otros servicios, lo ideal es hacerlo en este archivo

Main

Finalmente en nuestro archivo main.go , tendremos todas las llamadas necesarias para iniciar nuestro backend, en este caso los importantes por los momentos es la inicializacion de las variables de entorno y de las capas definidas en la función BuildContainer de bootstrap como ademas de la definición final del route a usar para cada proposito

package main

import (
    "api-golang/bootstrap"
    "api-golang/config"
    "api-golang/controller"
    "log"
    "net/http"

    _ "github.com/golang-migrate/migrate/v4/database/postgres"
    _ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
    cfg := config.LoadConfig()

    container := bootstrap.BuildContainer(cfg)

    // Invoke the container to inject the controller and configure the routes
    err := container.Invoke(func(productController *controller.ProductController) {
        http.HandleFunc("/productos", productController.GetProducts)
        http.HandleFunc("/producto", productController.CreateProduct)
    })

    if err != nil {
        log.Fatalf("Failed to invoke container: %v", err)
    }

    log.Println("Server started on port 8080")
    if err := http.ListenAndServe(":8080", nil); err != nil {
        log.Fatal(err)
    }
}

Una ultima cosa y muy importante es tener siempre pruebas unitarias, para Go es mucho mas sencillo, podemos definir test solo con el sufijo _test, Go automáticamente los reconoce al correr el comando go test, para tener un orden de los test de nuestro backend, coloque un test del controlador, en la ruta

/controller/product_controller_test.go

package controller

import (
    "api-golang/dto"
    "api-golang/models"
    "api-golang/services/mocks"
    "bytes"
    "encoding/json"
    "net/http"
    "net/http/httptest"
    "testing"

    "github.com/stretchr/testify/assert"
    "github.com/stretchr/testify/mock"
)

func TestCreateProduct(t *testing.T) {

    // Prepare de ProductService Interface
    mockService := new(mocks.ProductService)
    // Prepare de The Product Instance with data
    mockProduct := models.Product{Nombre: "Test Product", Precio: 10.99}
        // Prepare de The DTO with data to validate
    mockProductDTO := dto.ProductCreateDTO{Nombre: "Test Product", Precio: 10.99}

    // Mocking the service
    mockService.On("CreateProduct", mock.AnythingOfType("models.Product")).Return(mockProduct, nil)

    // Prepare the Controller and pass the Mock Service into the controller
    controller := NewProductController(mockService)

    // Http Request
    productJSON, _ := json.Marshal(mockProductDTO)
    req, _ := http.NewRequest("POST", "/product", bytes.NewBuffer(productJSON))
    rr := httptest.NewRecorder()

    // After the http request call we use the controller to use the CreateProduct function
    handler := http.HandlerFunc(controller.CreateProduct)
    handler.ServeHTTP(rr, req)

    assert.Equal(t, http.StatusOK, rr.Code)

    // Check the mock data vs response
    var returnedProduct models.Product
    json.Unmarshal(rr.Body.Bytes(), &returnedProduct)

    assert.Equal(t, mockProduct.Nombre, returnedProduct.Nombre)
    assert.Equal(t, mockProduct.Precio, returnedProduct.Precio)

    mockService.AssertExpectations(t)
}

Un detalle super genial que vi con Go, es una herramienta llamada Mockery, la cual es una herramienta que nos ayuda a construir mocks de la interfaz del servicio ProductService, y automaticamente nos deja la logica necesaria a usar para poder realizar el test del controlador junto con la interfaz del servicio, para ejecutar automaticamente las interfaces necesarias puedes ejecutar:

mockery --name=ProductService --output=services/mocks --outpkg=mocks --case=underscore

luego, como tenemos nuestros test por cada archivo a usar, el comando para los test queda como go test ./...

Un ultimo detalle, es poder tener en nuestro desarrollo local una manera de observar nuestros cambios con hard-reload, para Go, hay una herramienta llamada Air la cual es excelente para iniciar nuestro servidor local, y que escuche los constantes cambios que tengamos en nuestro código, para usarlo simplemente lo configuramos con air init y lo iniciamos ejecutando por consola air

Para probar el endpoint seria http://localhost:8080/productos

Listo !

Conclusion

Tenemos un backend inicial listo para usar para nuestros proyectos, realizando un repaso sobre lo que se ha explicado en este backend tenemos lo siguiente

-Arquitectura de 3 capas Repositorios, Servicios y Controladores

Configuración de la base de datos
Se aplicó la inyección de dependencias para desacoplar las capas de la aplicación.
Se centralizaron las configuraciones utilizando variables de entorno, permitiendo que el proyecto sea fácilmente adaptable a diferentes entornos
Manejo de Errores
Validacion de entradas usando Data Transfer Object (DTO)
ORM para interactuar con la base de datos
Migraciones
Pruebas Unitarias
Se integraron herramientas de desarrollo como mockery para la generación de mocks y herramientas de terceros para la mejora del flujo de trabajo de desarrollo
Hot Reloading con AIR

Siempre es bueno compartir conocimientos a nuestra comunidad, es la primera vez que realizo un articulo :D, asi que espero que este backend inicial sea util para mis colegas!

Saludos!

Codigo: https://github.com/jorge6242/api-golang