1. Convenciones y Estándares

src/
├── controllers/     # HTTP handlers
│   ├── userController.js
│   ├── orderController.js
│   └── productController.js
├── services/        # Business logic
│   ├── userService.js
│   ├── orderService.js
│   └── emailService.js
├── repositories/    # Data access
│   ├── userRepository.js
│   └── orderRepository.js
├── models/          # Entities, DTOs
│   ├── User.js
│   ├── Order.js
│   └── Product.js
├── middleware/      # Express/FastAPI middleware
│   ├── auth.js
│   ├── errorHandler.js
│   └── logger.js
├── utils/           # Helpers, utilities
│   ├── validators.js
│   └── formatters.js
├── config/          # Configuration
│   ├── database.js
│   └── env.js
└── tests/           # Tests (mirrors src/)
    ├── unit/
    └── integration/

src/
├── auth/                    # Feature: Authentication
│   ├── controllers/
│   │   └── authController.js
│   ├── services/
│   │   └── authService.js
│   ├── models/
│   │   └── User.js
│   ├── middleware/
│   │   └── jwtMiddleware.js
│   └── tests/
├── orders/                  # Feature: Order management
│   ├── controllers/
│   ├── services/
│   ├── models/
│   └── tests/
├── products/                # Feature: Product catalog
│   ├── controllers/
│   ├── services/
│   ├── models/
│   └── tests/
└── shared/                  # Código compartido
    ├── database/
    ├── utils/
    └── config/

src/
├── domain/                  # Core: Business logic
│   ├── entities/           # Pure domain objects
│   │   ├── User.ts
│   │   └── Order.ts
│   ├── value-objects/      # Immutable values
│   │   ├── Email.ts
│   │   └── Money.ts
│   ├── repositories/       # Interfaces (ports)
│   │   └── IUserRepository.ts
│   └── services/           # Business rules
│       └── OrderService.ts
├── application/             # Use cases
│   ├── commands/           # Write operations
│   │   ├── CreateUserCommand.ts
│   │   └── PlaceOrderCommand.ts
│   └── queries/            # Read operations
│       └── GetUserQuery.ts
├── infrastructure/          # Adapters (implementaciones)
│   ├── repositories/       # DB implementations
│   │   └── PostgresUserRepository.ts
│   ├── http/              # API adapters
│   │   ├── controllers/
│   │   └── routes/
│   ├── messaging/         # Event bus, queues
│   └── persistence/       # Migrations, seeds
└── tests/
    ├── unit/              # Domain + Application
    └── integration/       # Infrastructure

src/
├── domain/                      # Capa 1: Domain Model (Core)
│   ├── entities/               # Entidades de negocio
│   │   ├── User.ts
│   │   ├── Order.ts
│   │   └── Product.ts
│   ├── value-objects/          # Objetos inmutables
│   │   ├── Email.ts
│   │   ├── Money.ts
│   │   └── Address.ts
│   ├── aggregates/             # Raíces de agregados
│   │   └── OrderAggregate.ts
│   └── exceptions/             # Excepciones de dominio
│       └── InvalidEmailException.ts
├── domain-services/             # Capa 2: Domain Services
│   ├── PricingService.ts       # Lógica que no pertenece a una entidad
│   ├── InventoryValidator.ts
│   └── ShippingCalculator.ts
├── application/                 # Capa 3: Application Services
│   ├── use-cases/              # Casos de uso
│   │   ├── CreateOrderUseCase.ts
│   │   ├── ProcessPaymentUseCase.ts
│   │   └── UpdateUserProfileUseCase.ts
│   ├── interfaces/             # Puertos (interfaces)
│   │   ├── IOrderRepository.ts
│   │   ├── IEmailService.ts
│   │   └── IPaymentGateway.ts
│   └── dto/                    # Data Transfer Objects
│       ├── CreateOrderRequest.ts
│       └── OrderResponse.ts
└── infrastructure/              # Capa 4: Infrastructure
    ├── repositories/           # Implementaciones de repositorios
    │   ├── PostgresOrderRepository.ts
    │   └── MongoUserRepository.ts
    ├── services/               # Implementaciones de servicios
    │   ├── SendGridEmailService.ts
    │   └── StripePaymentGateway.ts
    ├── http/                   # Adaptadores HTTP
    │   ├── controllers/
    │   │   ├── OrderController.ts
    │   │   └── UserController.ts
    │   ├── routes/
    │   │   └── api.routes.ts
    │   └── middleware/
    │       ├── auth.middleware.ts
    │       └── error.middleware.ts
    ├── persistence/            # Migraciones, seeds
    │   ├── migrations/
    │   └── seeds/
    └── config/                 # Configuración
        ├── database.config.ts
        └── app.config.ts

src/
├── entities/                        # Círculo 1: Enterprise Business Rules
│   ├── User.ts                     # Entidades de negocio puras
│   ├── Order.ts
│   ├── Product.ts
│   └── value-objects/              # Value Objects
│       ├── Email.ts
│       ├── Money.ts
│       └── OrderStatus.ts
├── use-cases/                       # Círculo 2: Application Business Rules
│   ├── user/
│   │   ├── CreateUser.ts           # Casos de uso específicos
│   │   ├── UpdateUserProfile.ts
│   │   └── DeleteUser.ts
│   ├── order/
│   │   ├── PlaceOrder.ts
│   │   ├── CancelOrder.ts
│   │   └── GetOrderHistory.ts
│   ├── interfaces/                 # Puertos (definidos por Use Cases)
│   │   ├── repositories/
│   │   │   ├── IUserRepository.ts
│   │   │   └── IOrderRepository.ts
│   │   └── services/
│   │       ├── IEmailService.ts
│   │       └── IPaymentGateway.ts
│   └── dto/                        # Request/Response DTOs
│       ├── CreateUserRequest.ts
│       └── OrderResponse.ts
├── adapters/                        # Círculo 3: Interface Adapters
│   ├── controllers/                # Convertir HTTP → Use Cases
│   │   ├── UserController.ts
│   │   └── OrderController.ts
│   ├── presenters/                 # Formatear respuestas
│   │   ├── UserPresenter.ts
│   │   └── OrderPresenter.ts
│   ├── gateways/                   # Implementar interfaces de Use Cases
│   │   ├── PostgresUserRepository.ts
│   │   ├── MongoOrderRepository.ts
│   │   └── SendGridEmailGateway.ts
│   └── view-models/                # Modelos para UI
│       └── OrderViewModel.ts
└── frameworks/                      # Círculo 4: Frameworks & Drivers
    ├── web/                        # Framework web (Express, Fastify)
    │   ├── server.ts
    │   ├── routes/
    │   │   ├── user.routes.ts
    │   │   └── order.routes.ts
    │   └── middleware/
    │       ├── auth.middleware.ts
    │       └── error.middleware.ts
    ├── database/                   # ORM/Database setup
    │   ├── typeorm/
    │   │   ├── config.ts
    │   │   └── migrations/
    │   └── seeds/
    ├── external-services/          # APIs de terceros
    │   ├── stripe/
    │   └── sendgrid/
    └── config/                     # Configuración de frameworks
        ├── env.ts
        └── logger.ts

src/
├── contexts/                    # Bounded Contexts
│   ├── sales/                  # Subdominio: Ventas
│   │   ├── domain/
│   │   │   ├── aggregates/    # Order (root), OrderItem
│   │   │   │   ├── Order.ts
│   │   │   │   └── OrderItem.ts
│   │   │   ├── entities/
│   │   │   ├── value-objects/  # Money, Address
│   │   │   ├── events/        # OrderPlaced, OrderShipped
│   │   │   ├── repositories/  # Interfaces
│   │   │   └── services/      # Domain services
│   │   ├── application/       # Use cases
│   │   │   ├── commands/
│   │   │   └── queries/
│   │   ├── infrastructure/    # Adaptadores
│   │   │   ├── persistence/
│   │   │   └── http/
│   │   └── tests/
│   ├── inventory/             # Subdominio: Inventario
│   │   └── (misma estructura)
│   └── shipping/              # Subdominio: Envíos
│       └── (misma estructura)
├── shared-kernel/             # Código compartido entre contexts
│   ├── domain/
│   └── infrastructure/
└── anti-corruption-layer/     # Traducción entre contexts

src/
├── components/          # Todos los componentes
│   ├── Button.tsx
│   ├── Card.tsx
│   ├── Header.tsx
│   └── UserProfile.tsx
├── pages/              # Páginas/Routes
│   ├── Home.tsx
│   ├── Dashboard.tsx
│   └── Profile.tsx
├── hooks/              # Custom hooks
│   ├── useAuth.ts
│   └── useFetch.ts
├── services/           # API calls
│   ├── api.ts
│   └── authService.ts
├── store/              # State management
│   ├── slices/
│   └── store.ts
├── utils/              # Helpers
│   └── formatters.ts
├── types/              # TypeScript types
│   └── User.ts
└── assets/             # Images, fonts

src/
├── features/                # Features de negocio
│   ├── auth/               # Feature: Autenticación
│   │   ├── components/
│   │   │   ├── LoginForm.tsx
│   │   │   └── RegisterForm.tsx
│   │   ├── hooks/
│   │   │   └── useAuth.ts
│   │   ├── services/
│   │   │   └── authApi.ts
│   │   ├── store/
│   │   │   └── authSlice.ts
│   │   ├── types/
│   │   │   └── User.ts
│   │   └── pages/
│   │       ├── LoginPage.tsx
│   │       └── RegisterPage.tsx
│   ├── dashboard/          # Feature: Dashboard
│   │   ├── components/
│   │   ├── hooks/
│   │   └── pages/
│   └── profile/            # Feature: Perfil usuario
│       └── (similar)
├── shared/                  # Componentes reutilizables
│   ├── components/         # Button, Card, Modal
│   │   ├── ui/            # Componentes UI básicos
│   │   └── layout/        # Header, Sidebar, Footer
│   ├── hooks/             # useDebounce, useLocalStorage
│   ├── utils/             # Helpers generales
│   └── types/             # Types compartidos
└── app/                    # App-level config
    ├── routes/
    ├── store/
    └── providers/

src/
├── components/
│   ├── atoms/              # Componentes básicos indivisibles
│   │   ├── Button/
│   │   │   ├── Button.tsx
│   │   │   ├── Button.test.tsx
│   │   │   ├── Button.stories.tsx
│   │   │   └── Button.module.css
│   │   ├── Input/
│   │   ├── Label/
│   │   ├── Icon/
│   │   └── Avatar/
│   ├── molecules/          # Combinación de atoms
│   │   ├── SearchBar/      # Input + Button + Icon
│   │   ├── FormField/      # Label + Input + Error
│   │   ├── Card/           # Container con atoms
│   │   └── MenuItem/
│   ├── organisms/          # Secciones complejas
│   │   ├── Header/         # Logo + SearchBar + UserMenu
│   │   ├── ProductCard/    # Card + Button + Image + Price
│   │   ├── NavigationBar/
│   │   └── CommentThread/
│   ├── templates/          # Layouts de página
│   │   ├── MainLayout/     # Header + Sidebar + Content + Footer
│   │   ├── DashboardLayout/
│   │   └── AuthLayout/
│   └── pages/              # Instancias de templates con data
│       ├── HomePage/
│       ├── DashboardPage/
│       └── ProfilePage/
├── hooks/
├── services/
└── store/

src/
├── features/                # Por módulo de negocio
│   ├── auth/
│   │   ├── components/     # Componentes específicos de auth
│   │   │   └── LoginForm.tsx
│   │   ├── hooks/
│   │   └── pages/
│   ├── dashboard/
│   └── products/
└── shared/                  # Atomic Design para compartidos
    ├── atoms/              # Button, Input, Icon
    ├── molecules/          # SearchBar, FormField
    ├── organisms/          # Header, Sidebar
    ├── templates/          # MainLayout, DashboardLayout
    ├── hooks/
    └── utils/

monorepo/
├── apps/                    # Aplicaciones
│   ├── web/                # Frontend web (Next.js)
│   ├── mobile/             # Mobile app (React Native)
│   ├── admin/              # Admin panel
│   ├── api/                # Backend API
│   └── workers/            # Background jobs
├── packages/                # Librerías compartidas
│   ├── ui/                 # Design system compartido
│   │   ├── components/
│   │   └── package.json
│   ├── utils/              # Utilidades compartidas
│   ├── types/              # TypeScript types compartidos
│   ├── config/             # Configs (ESLint, TS, etc)
│   └── api-client/         # Cliente API compartido
├── tools/                   # Scripts build, codegen
├── docs/                    # Documentación
├── package.json            # Root package
├── turbo.json              # Turborepo config
└── nx.json                 # Nx config (alternativa)

feat(auth): add JWT authentication
fix(api): handle null user in /profile endpoint
docs(readme): update installation instructions
refactor(user-service): extract validation logic
test(auth): add unit tests for login flow
chore(deps): upgrade React to 18.2
```text

**Herramientas:** [commitlint](https://commitlint.js.org/), [husky](https://typicode.github.io/husky/)

### GitFlow vs Trunk-Based

| Aspecto | GitFlow | Trunk-Based |
| :-------- | :-------- | :------------ |
| **Branches** | `main`, `develop`, `feature/*`, `release/*`, `hotfix/*` | `main`, `feature/*` (short-lived) |
| **Merge a main** | Via `release` branch | Directo (tras CI/CD) |
| **Feature lifetime** | Días/semanas | <24 horas ideal |
| **Cuándo usar** | Releases planificados, equipos grandes | CI/CD continuo, deploy frecuente |

**Trunk-Based (recomendado moderno):**

```text
main ─────●─────●─────●────→ (siempre deployable)
           ↖    ↗
         feature (merge rápido)

1.2.3
│ │ └─ PATCH: Bug fixes
│ └─── MINOR: New features (backward compatible)
└───── MAJOR: Breaking changes

// locales/en.json
{
  "common": {
    "welcome": "Welcome",
    "logout": "Log out"
  },
  "errors": {
    "notFound": "Page not found",
    "serverError": "Something went wrong"
  }
}

// locales/es.json
{
  "common": {
    "welcome": "Bienvenido",
    "logout": "Cerrar sesión"
  }
}

# ❌ Mal
DATABASE_URL = "postgresql://localhost/mydb"

# ✅ Bien
import os
DATABASE_URL = os.getenv("DATABASE_URL")

DATABASE_URL=postgresql://localhost/mydb
SECRET_KEY=dev-secret-key-not-for-prod
DEBUG=true

# Dependencies
node_modules/
venv/
.venv/

# Build outputs
dist/
build/
*.pyc
__pycache__/

# Environment
.env
.env.local

# IDEs
.vscode/
.idea/
*.swp

# OS
.DS_Store
Thumbs.db

# Logs
*.log
logs/

# Testing
coverage/
.pytest_cache/

// package.json
{
  "scripts": {
    "lint": "eslint src/",
    "format": "prettier --write src/",
    "format:check": "prettier --check src/"
  },
  "husky": {
    "hooks": {
      "pre-commit": "npm run format && npm run lint"
    }
  }
}

// ❌ Mal: restating
// Incrementa contador
counter++;

// ✅ Bien: explica por qué
// Workaround: API retorna duplicados, deduplicar manualmente
// TODO: Reportar bug al team de backend (ticket: API-123)
const uniqueUsers = [...new Set(users)];

def calculate_discount(price: float, discount_percent: float) -> float:
    """
    Calcula precio con descuento aplicado.

    Args:
        price: Precio original
        discount_percent: Porcentaje de descuento (0-100)

    Returns:
        Precio final con descuento aplicado

    Raises:
        ValueError: Si discount_percent < 0 o > 100
    """
    if not 0 <= discount_percent <= 100:
        raise ValueError("Discount must be between 0 and 100")
    return price * (1 - discount_percent / 100)

/**
 * Validates email format using RFC 5322 regex
 * @param email - Email address to validate
 * @returns true if valid, false otherwise
 * @example
 * isValidEmail("user@example.com") // true
 * isValidEmail("invalid") // false
 */
function isValidEmail(email: string): boolean {
  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  return regex.test(email);
}