# Arquitectura Técnica y Flujos de Desarrollo

## Fundamentos de Arquitectura para Vibe Coding

### Diferencias con Desarrollo Tradicional

**Desarrollo Tradicional**:
- Planificación extensa antes de escribir código
- Arquitectura definida completamente upfront
- Cambios arquitectónicos son costosos
- Testing como fase separada

**Vibe Coding**:
- **Arquitectura evolutiva**: Se refina durante el desarrollo
- **Documentación viva**: Se actualiza con cada implementación
- **Feedback rápido**: Iteraciones cada pocas horas
- **Context-driven**: Decisiones basadas en contexto IA

### Principios de Arquitectura para IA

#### 1. Context-First Architecture
- **Documentación clara**: La IA necesita entender la estructura
- **Separación de responsabilidades**: Backend, frontend, database claramente definidos
- **Naming conventions**: Consistentes y descriptivos
- **File organization**: Estructura lógica y predecible

#### 2. Incremental Complexity
- **Start simple**: MVP funcional primero
- **Add layers**: Complejidad en iteraciones
- **Maintain clarity**: Cada adición debe ser comprensible por IA

#### 3. Error Recovery Friendly
- **Rollback capability**: Git branches por feature
- **Isolation**: Contenedores para servicios
- **Debugging support**: Logs y herramientas de desarrollo

## Flujo Backend: Arquitectura y Implementación

### ¿Qué es el Backend en Vibe Coding?

**Backend NO es solo base de datos**:
```
Frontend → Backend → Database
    ↑         ↓         ↑
  Usuario   Lógica    Datos
```

**Flujo completo**:
1. **Frontend**: Hace petición HTTP
2. **Backend**: Procesa, valida, transforma
3. **Database**: Almacena/recupera datos
4. **Backend**: Procesa respuesta  
5. **Frontend**: Muestra resultado al usuario

### Frameworks Recomendados por Caso de Uso

#### Para Proyectos Pequeños-Medianos
**FastAPI (Python)**:
- **Ideal para**: APIs REST, integración con IA/ML
- **Fortalezas**: Documentación automática, typing, performance
- **Casos de uso**: Chatbots, API wrappers, MVPs rápidos
- **Tiempo de desarrollo**: Días a semanas

```python
# Ejemplo FastAPI structure
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

app = FastAPI()

class ProjectCreate(BaseModel):
    name: str
    description: str

@app.post("/projects")
async def create_project(project: ProjectCreate):
    # Business logic here
    return {"id": 1, "name": project.name}
```

#### Para Proyectos Grandes/Escalables
**Django (Python)**:
- **Ideal para**: Aplicaciones complejas, admin panels, B2B
- **Fortalezas**: ORM potente, admin automático, ecosistema maduro
- **Casos de uso**: SaaS complejos, plataformas de contenido
- **Tiempo de desarrollo**: Semanas a meses

```python
# Django models example
from django.db import models

class Project(models.Model):
    name = models.CharField(max_length=200)
    description = models.TextField()
    created_at = models.DateTimeField(auto_now_add=True)
    
    def __str__(self):
        return self.name
```

#### Alternativas por Lenguaje
- **Node.js**: Express, Nest.js para equipos JavaScript
- **PHP**: Laravel para desarrolladores PHP
- **Java**: Spring Boot para enterprise

### Decisión Framework: Matriz de Elección

| Criterio | FastAPI | Django | Node.js | Laravel |
|----------|---------|---------|---------|---------|
| **Velocidad desarrollo** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **Escalabilidad** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐⭐ |
| **IA/ML Integration** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐ | ⭐ |
| **Community/Resources** | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
| **Vibe Coding Support** | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ | ⭐⭐⭐ |

## Bases de Datos y Almacenamiento

### PostgreSQL: La Elección Predilecta

**¿Por qué PostgreSQL?**:
- **Versatilidad**: Relacional + NoSQL features
- **Performance**: Excelente para aplicaciones modernas  
- **JSON support**: Flexibility sin perder consistency
- **Ecosystem**: Herramientas maduras y bien integradas
- **AI Compatibility**: Extensiones para vector search, ML

**Casos donde NO usar PostgreSQL**:
- Aplicaciones extremadamente simples (SQLite suficiente)
- Big Data pure (Cassandra, MongoDB mejor opción)
- Cache-heavy apps (Redis como primaria)

### Arquitectura de Datos Recomendada

#### Estructura Básica SaaS
```sql
-- Users y autenticación
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW(),
    is_active BOOLEAN DEFAULT TRUE
);

-- Core business entity
CREATE TABLE projects (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    data JSONB, -- Flexibility for evolving requirements
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

-- Relationships y features adicionales
CREATE TABLE project_versions (
    id SERIAL PRIMARY KEY,
    project_id INTEGER REFERENCES projects(id),
    version_number INTEGER NOT NULL,
    changes JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);
```

#### Indexes Esenciales
```sql
-- Performance crítico
CREATE INDEX idx_projects_user_id ON projects(user_id);
CREATE INDEX idx_projects_created_at ON projects(created_at DESC);
CREATE INDEX idx_project_versions_project_id ON project_versions(project_id);

-- Full-text search
CREATE INDEX idx_projects_search ON projects USING GIN(to_tsvector('english', name || ' ' || description));
```

### Alternativas y Cuando Usarlas

#### Supabase vs Self-Hosted
**Supabase (Database-as-a-Service)**:
- **Pros**: Setup rápido, auth incluido, real-time
- **Cons**: Vendor lock-in, costos escalables, menos control
- **Cuándo usar**: MVPs, prototipos, equipos pequeños

**Self-Hosted PostgreSQL**:
- **Pros**: Control total, costos predecibles, migración fácil
- **Cons**: Setup inicial más complejo, mantenimiento
- **Cuándo usar**: Producción seria, equipos con experiencia

## Containerización con Docker

### ¿Por qué Docker es Esencial para Vibe Coding?

**Problemas que resuelve**:
- **"Funciona en mi máquina"**: Environment consistency
- **Setup complexity**: Un comando para levantar todo
- **Service isolation**: Backend, frontend, DB separados
- **Development/Production parity**: Mismo entorno siempre

### Docker Compose: La Base del Desarrollo

#### Template Completo para SaaS
```yaml
version: '3.8'

services:
  # Frontend (Next.js)
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
    volumes:
      - ./frontend:/app
      - /app/node_modules
      - /app/.next
    environment:
      - NODE_ENV=development
      - NEXT_PUBLIC_API_URL=http://localhost:8000
    depends_on:
      - backend

  # Backend (FastAPI)  
  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile.dev
    ports:
      - "8000:8000"
    volumes:
      - ./backend:/app
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/devdb
      - PYTHONPATH=/app
      - RELOAD=true
    depends_on:
      - db
      - redis

  # Database
  db:
    image: postgres:15-alpine
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=devdb
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./backend/migrations:/docker-entrypoint-initdb.d

  # Cache/Sessions
  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

  # Database Management
  adminer:
    image: adminer:latest
    ports:
      - "8080:8080"
    depends_on:
      - db
    environment:
      - ADMINER_DEFAULT_SERVER=db

  # Email Development (opcional)
  mailcatcher:
    image: schickling/mailcatcher
    ports:
      - "1080:1080"  # Web interface
      - "1025:1025"  # SMTP

volumes:
  postgres_data:
  redis_data:
```

#### Dockerfiles para Desarrollo

**Frontend Dockerfile.dev**:
```dockerfile
FROM node:18-alpine

WORKDIR /app

# Install dependencies
COPY package*.json ./
RUN npm install

# Copy source
COPY . .

# Expose port
EXPOSE 3000

# Development command
CMD ["npm", "run", "dev"]
```

**Backend Dockerfile.dev**:
```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy source
COPY . .

# Expose port  
EXPOSE 8000

# Development command
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
```

### Comandos Docker Esenciales

```bash
# Levantar entorno completo
docker-compose up -d

# Rebuild después de cambios en Dockerfile
docker-compose up --build

# Ver logs de servicios
docker-compose logs -f [service_name]

# Ejecutar comandos en contenedor
docker-compose exec backend python manage.py migrate
docker-compose exec frontend npm run build

# Parar y limpiar
docker-compose down
docker-compose down -v  # También elimina volúmenes
```

## Git y Control de Versiones para Vibe Coding

### Metodología de Ramas Optimizada para IA

#### Estructura de Ramas

```
main                    # Producción estable
├── dev                # Desarrollo integrado  
    ├── feature/auth   # Feature específica
    ├── feature/dashboard
    └── feature/api-v2
```

**¿Por qué esta estructura?**
- **main**: Solo código probado y estable
- **dev**: Integración continua de features  
- **feature/***: Desarrollo aislado de cada funcionalidad

#### Workflow Recomendado

```bash
# 1. Crear nueva feature
git checkout dev
git pull origin dev
git checkout -b feature/user-authentication

# 2. Desarrollo con commits frecuentes
git add .
git commit -m "feat: add user registration endpoint"
git push origin feature/user-authentication

# 3. Merge a dev cuando feature completa
git checkout dev
git merge feature/user-authentication
git push origin dev

# 4. Deploy a main semanalmente/cuando estable
git checkout main
git merge dev
git tag v1.0.0
git push origin main --tags
```

### Commits Descriptivos para IA

**Formato recomendado**:
```
<type>: <description>

<opcional: body explicando qué y por qué>
```

**Tipos estándar**:
- `feat`: Nueva funcionalidad
- `fix`: Bug fix
- `docs`: Cambios en documentación
- `style`: Cambios de formato (no afectan lógica)
- `refactor`: Refactoring sin cambio funcional
- `test`: Agregar o modificar tests

**Ejemplos buenos**:
```bash
git commit -m "feat: implement JWT authentication for API endpoints"
git commit -m "fix: resolve database connection timeout in production"
git commit -m "docs: update API documentation with new auth endpoints"
```

### Git para Trabajo con IA

#### .gitignore Optimizado
```gitignore
# Environment variables
.env
.env.local
.env.production

# Dependencies
node_modules/
__pycache__/
*.pyc

# Build outputs
.next/
dist/
build/

# Database
*.db
*.sqlite

# Logs
*.log
logs/

# AI and development files
.cursorrules.local
gemini.local.md
claude.local.md

# IDE
.vscode/settings.json
.idea/

# Docker
docker-compose.override.yml
```

#### Hooks para Automatización

**pre-commit hook** (`.git/hooks/pre-commit`):
```bash
#!/bin/bash
# Run linting before commits
npm run lint
python -m flake8 backend/

# Update documentation
echo "Last updated: $(date)" >> docs/last-updated.md
```

## Arquitecturas por Tipo de Aplicación

### SaaS/Dashboard
**Stack recomendado**:
- **Frontend**: Next.js + TypeScript + Tailwind
- **Backend**: FastAPI + SQLAlchemy
- **Database**: PostgreSQL + Redis (cache)
- **Auth**: JWT + bcrypt
- **Payments**: Stripe

**Estructura de directorios**:
```
saas-project/
├── frontend/
│   ├── app/            # Next.js app directory
│   ├── components/     # React components
│   ├── lib/           # Utilities
│   └── types/         # TypeScript definitions
├── backend/
│   ├── app/
│   │   ├── api/       # API endpoints
│   │   ├── models/    # Database models
│   │   ├── services/  # Business logic
│   │   └── utils/     # Utilities
│   └── alembic/       # Database migrations
├── docs/              # Vibe planning outputs
├── design/            # UI mockups
└── docker-compose.yml
```

### Content Platform/Blog
**Stack recomendado**:
- **Frontend**: Next.js + MDX
- **Backend**: Node.js + Express (o headless CMS)
- **Database**: PostgreSQL + Full-text search
- **Media**: CloudFlare R2 o AWS S3

### E-commerce
**Stack recomendado**:
- **Frontend**: Next.js + TypeScript
- **Backend**: Django + Django REST Framework
- **Database**: PostgreSQL + Redis
- **Payments**: Stripe + PayPal
- **Search**: Elasticsearch

### API/Microservice
**Stack recomendado**:
- **Framework**: FastAPI o Express.js
- **Database**: PostgreSQL o MongoDB
- **Cache**: Redis
- **Queue**: Celery (Python) o Bull (Node.js)
- **Docs**: Auto-generated (FastAPI) o Swagger

## Patrones de Desarrollo para IA

### Repository Pattern
```python
# backend/app/repositories/user_repository.py
from typing import List, Optional
from sqlalchemy.orm import Session
from app.models.user import User

class UserRepository:
    def __init__(self, db: Session):
        self.db = db
    
    def create(self, user_data: dict) -> User:
        user = User(**user_data)
        self.db.add(user)
        self.db.commit()
        return user
    
    def find_by_email(self, email: str) -> Optional[User]:
        return self.db.query(User).filter(User.email == email).first()
```

### Service Layer Pattern  
```python
# backend/app/services/auth_service.py
from app.repositories.user_repository import UserRepository
from app.utils.auth import hash_password, verify_password, create_access_token

class AuthService:
    def __init__(self, user_repo: UserRepository):
        self.user_repo = user_repo
    
    def register(self, email: str, password: str) -> dict:
        # Business logic for registration
        hashed_password = hash_password(password)
        user = self.user_repo.create({
            "email": email,
            "password_hash": hashed_password
        })
        token = create_access_token(user.id)
        return {"user": user, "token": token}
```

### API Response Patterns
```python
# Consistent API responses
from pydantic import BaseModel
from typing import Generic, TypeVar, Optional

T = TypeVar('T')

class APIResponse(BaseModel, Generic[T]):
    success: bool
    data: Optional[T] = None
    message: Optional[str] = None
    errors: Optional[List[str]] = None

# Usage
@app.post("/users", response_model=APIResponse[UserOut])
async def create_user(user_data: UserCreate):
    try:
        user = auth_service.register(user_data.email, user_data.password)
        return APIResponse(success=True, data=user, message="User created successfully")
    except Exception as e:
        return APIResponse(success=False, errors=[str(e)])
```

## Testing en Vibe Coding

### Testing Strategy
1. **Unit tests**: Para lógica de negocio crítica
2. **Integration tests**: Para APIs principales
3. **E2E tests**: Para user journeys críticos (cuando app madura)

### Testing con IA
```python
# pytest example
def test_user_registration():
    # Given
    user_data = {"email": "test@example.com", "password": "securepass"}
    
    # When  
    response = client.post("/auth/register", json=user_data)
    
    # Then
    assert response.status_code == 201
    assert "token" in response.json()["data"]
```

## Performance y Optimización

### Database Optimization
```sql
-- Indexes for common queries
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);
CREATE INDEX CONCURRENTLY idx_projects_user_created ON projects(user_id, created_at DESC);

-- Partial indexes for common filters
CREATE INDEX CONCURRENTLY idx_projects_active ON projects(user_id) WHERE is_active = true;
```

### Caching Strategy
```python
# Redis caching example
import redis
from functools import wraps

redis_client = redis.Redis(host='redis', port=6379, db=0)

def cache_result(expiration=3600):
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            cache_key = f"{func.__name__}:{hash(str(args) + str(kwargs))}"
            
            # Try to get from cache
            cached = redis_client.get(cache_key)
            if cached:
                return json.loads(cached)
            
            # Execute function and cache result
            result = func(*args, **kwargs)
            redis_client.setex(cache_key, expiration, json.dumps(result))
            return result
        return wrapper
    return decorator

@cache_result(expiration=1800)
def get_user_projects(user_id: int):
    return project_repo.find_by_user_id(user_id)
```

## Deployment y DevOps

### Preparación para Producción
```dockerfile
# Production Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM node:18-alpine AS runner
WORKDIR /app
COPY --from=builder /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json

EXPOSE 3000
CMD ["npm", "start"]
```

### Environment Configuration
```yaml
# docker-compose.prod.yml
version: '3.8'
services:
  frontend:
    image: myapp/frontend:latest
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_API_URL=https://api.myapp.com
    restart: unless-stopped

  backend:
    image: myapp/backend:latest
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - JWT_SECRET=${JWT_SECRET}
    restart: unless-stopped
```

## Troubleshooting Arquitectónico

### Problemas Comunes de Arquitectura

#### "No puedo conectar frontend con backend"
**Diagnóstico**:
```bash
# Verificar que servicios estén corriendo
docker-compose ps

# Verificar conectividad
curl http://localhost:8000/health

# Verificar logs
docker-compose logs backend
```

**Soluciones**:
- Verificar CORS configuration en backend
- Confirmar URLs de API en frontend
- Revisar variables de entorno

#### "Database connection failed"
**Diagnóstico**:
```bash
# Conectar directamente a DB
docker-compose exec db psql -U postgres -d devdb

# Verificar variables de entorno
docker-compose exec backend env | grep DATABASE
```

#### "Build fails in production"
**Soluciones**:
- Revisar diferencias entre Dockerfile.dev y Dockerfile.prod
- Verificar que todas las dependencias estén en package.json/requirements.txt
- Comprobar variables de entorno de build

## Siguientes Pasos

Una vez dominada la arquitectura:
1. **Implementar CI/CD**: GitHub Actions o similar
2. **Monitoring**: Logs, métricas, alertas
3. **Security**: HTTPS, OWASP guidelines, penetration testing
4. **Scaling**: Load balancing, database replication
5. **Advanced patterns**: Microservices, event-driven architecture