rckrdmrd/workspace
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
00c09054e8
workspace/projects/gamilit/docs/97-adr/README.md
rckrdmrd ea1879f4ad feat: Initial workspace structure with multi-level Git configuration 
- Configure workspace Git repository with comprehensive .gitignore
- Add Odoo as submodule for ERP reference code
- Include documentation: SETUP.md, GIT-STRUCTURE.md
- Add gitignore templates for projects (backend, frontend, database)
- Structure supports independent repos per project/subproject level

Workspace includes:
- core/ - Reusable patterns, modules, orchestration system
- projects/ - Active projects (erp-suite, gamilit, trading-platform, etc.)
- knowledge-base/ - Reference code and patterns (includes Odoo submodule)
- devtools/ - Development tools and templates
- customers/ - Client implementations template

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-08 10:44:23 -06:00

14 KiB
Raw Blame History

Architecture Decision Records (ADR)

Carpeta: docs/97-adr/ Propósito: Documentar decisiones arquitectónicas importantes del proyecto Última actualización: 2025-11-23

📋 ¿Qué son los ADRs?

Architecture Decision Record (ADR) es un documento que captura una decisión arquitectónica importante junto con su contexto y consecuencias.

¿Por qué usamos ADRs?

  1. Memoria del proyecto: Explicar "por qué" se tomaron decisiones
  2. Onboarding: Nuevos miembros entienden decisiones históricas
  3. Evitar rediscusión: Decisiones documentadas no se recuestionan sin contexto
  4. Accountability: Claridad sobre quién decidió qué y cuándo
  5. Learning: Aprender de decisiones pasadas (buenas y malas)

Cuándo crear un ADR

Crea un ADR cuando:

  • ✅ Cambias arquitectura fundamental (monorepo, microservicios, etc.)
  • ✅ Adoptas nueva tecnología importante (framework, database, etc.)
  • ✅ Defines patrones de diseño a seguir
  • ✅ Tomas decisión que afecta a múltiples equipos
  • ✅ Eliges entre alternativas con trade-offs significativos

NO creas un ADR para:

  • ❌ Decisiones triviales (naming conventions simples)
  • ❌ Decisiones fácilmente reversibles
  • ❌ Implementaciones específicas (eso va en docs técnicas)

📐 Formato de ADR

Usamos el formato Michael Nygard ADR template:

# ADR-XXXX: [Título de la Decisión]

**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** YYYY-MM-DD
**Deciders:** [Lista de stakeholders]
**Tags:** [categorías]

---

## Context

[Descripción del problema o situación que motiva la decisión]
[Constraints, fuerzas en juego, contexto de negocio]

## Decision

[La decisión tomada, explicada claramente]
[Qué vamos a hacer]

## Alternatives Considered

### Alternative 1: [Nombre]
**Pros:**
- ...

**Cons:**
- ...

**Decisión:** Rechazada porque...

### Alternative 2: [Nombre]
...

## Consequences

### Positivas ✅
[Qué mejora con esta decisión]

### Negativas ⚠️
[Qué empeora o se complica]

## References

[Links a docs, papers, blog posts relevantes]

---

**Status:** [Current status]
**Date Created:** YYYY-MM-DD
**Last Updated:** YYYY-MM-DD
**Supersedes:** [ADR anterior si aplica]
**Superseded by:** [ADR que reemplaza este]

📚 ADRs Existentes

✅ ADR-0001: Adopción de Arquitectura Monorepo

Date: 2025-11-01 | Status: ✅ Implemented | Category: Architecture

Consolidar 4 repositorios separados en un monorepo unificado.

→ Leer ADR completo

✅ ADR-0002: Implementación del Sistema SIMCO

Date: 2025-11-05 | Status: ✅ Implemented | Category: Documentation

Sistema Indexado Modular por Contexto usando _MAP.md para AI agents y developers.

→ Leer ADR completo

✅ ADR-0003: Team vs Guild en Social Features

Date: 2025-11-08 | Status: ✅ Implemented | Category: Social Features

Usar "Guild" en lugar de "Team" para funcionalidades sociales (coherente con temática Maya).

→ Leer ADR completo

✅ ADR-007: Schemas sin Tablas en PostgreSQL

Date: 2025-11-11 | Status: ✅ Accepted | Category: Database

Permitir schemas vacíos en PostgreSQL para reserva futura.

→ Leer ADR completo

✅ ADR-008: Sistema Dual exercise_type + Categorías Pedagógicas

Date: 2025-11-11 | Status: ✅ Implemented | Category: Database

Sistema dual con exercise_type (35 tipos) + mapeo a categorías pedagógicas.

→ Leer ADR completo

✅ ADR-009: Duración del Ejercicio 3.4 - Podcast Argumentativo

Date: 2025-11-23 | Status: ✅ Implemented | Category: Content Design

Mantener duración de 2 minutos (vs 3) para podcast argumentativo.

→ Leer ADR completo

✅ ADR-010: DocumentoDeDiseño como Fuente de Verdad

Date: 2025-11-23 | Status: ✅ Accepted | Category: Architecture

El DocumentoDeDiseño_Mecanicas_GAMILIT_v6_1.md es la fuente de verdad para módulos y ejercicios.

→ Leer ADR completo

✅ ADR-011: Estructura de API Clients en Frontend

Date: 2025-11-23 | Status: ✅ Accepted | Category: Frontend

Estructura estándar para API clients con módulos por dominio.

→ Leer ADR completo

✅ ADR-012: Inicialización Automática de Usuarios mediante Trigger

Date: 2025-11-24 | Status: ✅ Implemented | Category: Database

Trigger que inicializa automáticamente registros de gamificación al registrar usuarios.

→ Leer ADR completo

✅ ADR-013: Adopción de React Query (TanStack Query v5)

Date: 2025-11-23 | Status: ✅ Implemented | Category: Frontend

TanStack Query v5 como solución estándar para manejo de estado asíncrono.

→ Leer ADR completo

✅ ADR-014: Nil-Safety Patterns

Date: 2025-11-23 | Status: ✅ Accepted | Category: Frontend

Optional Chaining (?.) y Nullish Coalescing (??) como patrón estándar.

→ Leer ADR completo

✅ ADR-015: Centralización de Rutas API en apiConfig.ts

Date: 2025-11-24 | Status: ✅ Implemented | Category: Frontend

Single Source of Truth para rutas API en apiConfig.ts (241 rutas).

→ Leer ADR completo

✅ ADR-016: Simplificar Backend XP Acumulación

Date: 2025-11-24 | Status: ✅ Implemented | Category: Backend

Delegar promoción de rangos completamente a triggers de base de datos.

→ Leer ADR completo

✅ ADR-017: Admin Portal Avanzado vs Alcance Inicial

Date: 2025-11-24 | Status: ✅ Accepted | Category: Architecture

Documentar discrepancia entre alcance inicial EAI-005 y portal admin implementado (~75 endpoints).

→ Leer ADR completo

✅ ADR-018: Eliminación de Carpetas Migrations

Date: 2025-11-24 | Status: ✅ Accepted | Category: Database

Eliminar carpetas migrations/ para cumplir Política de Carga Limpia.

→ Leer ADR completo

✅ ADR-019: Adopción de Zod v3 para Runtime Validation

Date: 2025-11-23 | Status: ✅ Accepted | Category: Frontend

Zod v3 como solución estándar para validación de runtime en frontend.

→ Leer ADR completo

✅ ADR-020: Soporte de Múltiples Alternativas en Completar Espacios

Date: 2025-11-24 | Status: ✅ Implemented | Category: Database

Función validate_fill_in_blank soporta múltiples respuestas válidas.

→ Leer ADR completo

✅ ADR-021: Estandarización de Recompensas XP en Ejercicios

Date: 2025-11-24 | Status: ✅ Implemented | Category: Gamification

Estandarizar 100 XP / 20 ML Coins por ejercicio para progresión consistente.

→ Leer ADR completo

✅ ADR-026: SIMCO v2 - Estructura Modular

Date: 2025-11-08 | Status: ✅ Accepted | Category: Documentation

Evolucionar SIMCO a v2 con estructura modular y templates estandarizados.

→ Leer ADR completo

🗺️ Navegación

Por Estado

Implemented/Accepted (19):

Por Categoría

Architecture (4):

  • ADR-0001: Monorepo Architecture
  • ADR-0002: SIMCO System
  • ADR-010: Documento Diseño Fuente Verdad
  • ADR-017: Admin Portal Avanzado

Database (5):

  • ADR-007: Schemas sin Tablas
  • ADR-008: Sistema Dual exercise_type
  • ADR-012: Automatic User Initialization Trigger
  • ADR-018: Removal Migrations Folders
  • ADR-020: Validación Alternativas Fill-in-Blank

Frontend (5):

  • ADR-011: Frontend API Client Structure
  • ADR-013: React Query Adoption
  • ADR-014: Nil-Safety Patterns
  • ADR-015: Centralized API Routes
  • ADR-019: Runtime Validation Zod

Backend (1):

  • ADR-016: Simplificar Backend XP

Gamification (1):

  • ADR-021: Estandarización Recompensas XP

Documentation (2):

  • ADR-0002: SIMCO
  • ADR-026: SIMCO v2

Social Features (1):

  • ADR-0003: Team vs Guild

Content Design (1):

  • ADR-009: Duración Podcast Ejercicio 3.4

📝 Cómo Crear un Nuevo ADR

Paso 1: Determinar el Número

# Ver último ADR
ls docs/97-adr/ | grep ADR | sort -V | tail -1
# Output: ADR-026-simco-v2-estructura-modular.md

# Siguiente número disponible: ADR-022, ADR-023, ADR-024, ADR-025, ADR-027...

Convención de Numeración:

  • Formato estándar: ADR-XXX o ADR-0XXX (consistente por rango)
  • Próximos disponibles: ADR-022, ADR-023, ADR-024, ADR-025, ADR-027+
  • Nota: ADR-026 ya existe, continuar desde ADR-022 o ADR-027+

Paso 2: Crear Archivo

# Copiar template (si existe)
cp docs/97-adr/ADR-TEMPLATE.md docs/97-adr/ADR-010-nombre-decision.md

# O crear desde cero
touch docs/97-adr/ADR-010-nombre-decision.md

# Editar con tu editor
code docs/97-adr/ADR-010-nombre-decision.md

Paso 3: Llenar Secciones

  1. Context: ¿Qué problema estamos resolviendo? ¿Por qué ahora?
  2. Decision: ¿Qué vamos a hacer? Sea específico.
  3. Alternatives Considered: ¿Qué otras opciones había? ¿Por qué no las elegimos?
  4. Consequences: ¿Qué mejora? ¿Qué empeora?

Paso 4: Review

  1. Pedir review a stakeholders relevantes
  2. Discutir en team meeting si es controversial
  3. Mergear cuando hay consenso

Paso 5: Actualizar README

# Agregar a este README.md en sección "ADRs Existentes"

💡 Best Practices

1. Escribe ADRs en Tiempo Presente

❌ Malo:

"We decided to use React"

✅ Bueno:

"We use React for frontend development"

2. Explica el "Por Qué", no el "Cómo"

❌ Malo:

"React uses virtual DOM for rendering"

✅ Bueno:

"We chose React because our team has 3 years of experience with it, and the component ecosystem is mature"

3. Documenta Alternatives Seriously

No escribas strawman alternatives. Si no consideraste seriamente una alternativa, no la incluyas.

✅ Bueno:

### Alternative: Vue 3
**Pros:**
- Composition API similar to React hooks
- Smaller bundle size (30% smaller)
- Better TypeScript support than Vue 2

**Cons:**
- Team no tiene experiencia
- Ecosystem menos maduro para enterprise
- Menos candidatos en hiring pipeline

**Decisión:** Rechazada - Team experience outweighs technical benefits

4. Actualiza Status

Si una decisión cambia:

**Status:** ~~Accepted~~ → **Superseded by ADR-0010**

5. Link Related ADRs

## Related ADRs
- [ADR-0001: Monorepo](./ADR-0001-monorepo-architecture.md) - Enables SIMCO
- [ADR-0005: JWT](./ADR-0005-jwt-auth.md) - Authentication strategy

🔍 Búsqueda de ADRs

Por Keyword

# Buscar ADRs sobre "database"
grep -i "database" docs/97-adr/ADR-*.md

# Buscar decisiones sobre "performance"
grep -i "performance" docs/97-adr/ADR-*.md

Por Status

# Ver ADRs accepted
grep "Status.*Accepted" docs/97-adr/ADR-*.md

# Ver ADRs deprecated
grep "Status.*Deprecated" docs/97-adr/ADR-*.md

📚 Recursos

ADR Methodologies:

Examples from Open Source:

Books:

📞 Contacto

Preguntas sobre ADRs:

  • Slack: #gamilit-architecture
  • Owner: @tech-lead

Proponer nuevo ADR:

  1. Crear issue en GitHub con label "adr"
  2. Discutir en #gamilit-architecture
  3. Si hay consenso, crear ADR

Review de ADR:

  • Requiere aprobación de Tech Lead + 2 stakeholders relevantes

Última actualización: 2025-11-29 Total ADRs: 19 (Accepted/Implemented: 19) Coverage: Architecture, Documentation, Database, Frontend, Backend, Gamification, Social Features, Content Design