Ponti Backend Development Rules

Comprehensive development guidelines for the Ponti backend project, a Go-based API with strict conventions around precision, architecture, and bilingual code practices.

Critical Rules

**NEVER:**

Use hardcoded values unless explicitly authorized

Use `ROUND()` in SQL migrations (maintain full precision)

Change anything beyond the surgical scope of the request

Implement before getting approval

**ALWAYS:**

Use dynamic and configurable parameters

Start responses with a TLDR summary

Wait for acceptance before implementing

Language Conventions

**Comments:** Spanish (`//`, `/* */`, `--`)

**Code:** English (variables, functions, types)

**TODOs:** English

Go Style Guidelines

Type Usage

Use **pointers** for non-slice fields

Use **slices as values** (`[]Type`)

Use `decimal.Decimal` for monetary fields

Use **3 decimal precision** in dashboard calculations

Always include `shareddomain.Base` at the end of structs

Example

```go

type Product struct {

ID *int64

Name string

Price decimal.Decimal // Para campos monetarios

Categories []string // Slice como valor

shareddomain.Base

}

```

Architecture Patterns

Layer Responsibilities

**Adapters:** Use DTOs for external communication

**Use Cases:** Work only with primitives or domain types

**Repository:** Use models from the `models` package

**Migrations:** Separate by entity

Data Flow

```

HTTP Request → Adapter (DTO) → Use Case (Domain) → Repository (Model) → Database

```

Database Guidelines

Migrations

**Prioritize SQL migrations** over Go models

**Never modify existing migrations** — create new ones

Use `seeds-dashboard.sql` for test data

**NEVER use `ROUND()`** in SQL migrations (maintain full precision)

Write migrations in English, comments in Spanish

Example Migration

```sql

-- Agregar campo de precio con precisión completa

ALTER TABLE products ADD COLUMN price NUMERIC(15,3) NOT NULL DEFAULT 0;

```

Calculations

Use database values for percentages

Don't recalculate in repository if already in DB

Use `fix_labors_list` view for labor calculations

Testing Standards

Approach

**Table-driven tests** for comprehensive coverage

Use **gomock** for mocking dependencies

**Execute tests immediately** without asking

Example

```go

func TestCalculateTotal(t *testing.T) {

tests := []struct {

name string

input decimal.Decimal

expected decimal.Decimal

}{

{"case 1", decimal.NewFromFloat(100.5), decimal.NewFromFloat(100.5)},

}

for _, tt := range tests {

t.Run(tt.name, func(t *testing.T) {

// test implementation

})

}

```

Docker Workflow

Commands run **inside containers**

Use **make targets** for common operations

Work on **one project at a time**, never more

Common Commands

```bash

make test # Run tests in container

make migrate # Run migrations

make seed # Load seed data

```

Error Handling

Use **consistent error types**

Handle **domain errors** appropriately

**Don't perform rollback analysis** — focus on making it work

Return meaningful error messages

Example

```go

if err != nil {

return nil, fmt.Errorf("error al procesar producto: %w", err)

}

```

API Testing with curl

Always use these headers for testing:

```bash

curl -H "X-API-KEY: abc123secreta" \

-H "X-USER-ID: 123" \

http://localhost:8080/api/endpoint

```

Implementation Workflow

1. **Read the request carefully** — understand the surgical scope

2. **Provide TLDR summary** of proposed approach

3. **Wait for approval** before implementing

4. **Implement surgically** — change only what's necessary

5. **Run tests immediately** without asking

6. **Verify with curl** using proper headers

Code Review Checklist

Before submitting changes, verify:

[ ] No hardcoded values (unless approved)

[ ] No `ROUND()` in SQL migrations

[ ] Comments in Spanish, code in English

[ ] `decimal.Decimal` used for money

[ ] Pointers used for non-slice fields

[ ] `shareddomain.Base` at end of structs

[ ] Tests written and passing

[ ] Only surgical changes made

Notes

This skill enforces strict conventions for a production backend where **precision matters** (financial calculations), **architecture is clean** (layered), and **bilingual practices** maintain code clarity for Spanish-speaking teams while following English coding standards.

Ponti Backend Development Rules

Ponti Backend Development Rules

Critical Rules

Language Conventions

Go Style Guidelines

Type Usage

Example

Architecture Patterns

Layer Responsibilities

Data Flow

Database Guidelines

Migrations

Example Migration

Calculations

Testing Standards

Approach

Example

Docker Workflow

Common Commands

Error Handling

Example

API Testing with curl

Implementation Workflow

Code Review Checklist

Notes

Reviews (0)