workspace/GIT-STRUCTURE.md

Estructura Git del Workspace

Repositorio Principal

• URL Remota: https://github.com/rckrdmrd/workspace.git
• Branch principal: main

Arquitectura de Repositorios

Este workspace implementa una arquitectura de repositorios multinivel que permite:

1. Repositorio maestro - Contiene todo el workspace (este repositorio)
2. Repositorios por proyecto - Cada proyecto puede tener su propio repositorio independiente
3. Repositorios por subproyecto - Verticales o componentes específicos pueden tener repositorios propios

workspace/                          # Repo: rckrdmrd/workspace.git
├── core/                           # Incluido en workspace
├── projects/
│   ├── erp-suite/                  # Puede tener repo independiente
│   │   └── apps/
│   │       └── verticales/
│   │           └── construccion/   # Puede tener repo independiente
│   ├── gamilit/                    # Puede tener repo independiente
│   └── trading-platform/           # Puede tener repo independiente
├── customers/                      # Incluido en workspace
├── knowledge-base/
│   └── reference/
│       └── odoo/odoo-18.0/         # SUBMODULE: github.com/odoo/odoo.git
└── devtools/                       # Incluido en workspace

Submodules (Referencias Externas)

El workspace utiliza git submodules para referencias externas que tienen su propio repositorio.

Submodules Incluidos

Submodule	URL	Descripción
knowledge-base/reference/odoo/odoo-18.0	https://github.com/odoo/odoo.git	Código fuente de Odoo (referencia ERP)

Comandos de Submodules

# Clonar workspace CON submodules (recomendado)
git clone --recurse-submodules https://github.com/rckrdmrd/workspace.git

# Si ya clonaste sin submodules, inicialízalos
git submodule update --init --recursive

# Clone superficial (más rápido, menos espacio)
git submodule update --init --depth 1

# Actualizar submodules a última versión
git submodule update --remote --merge

# Ver estado de submodules
git submodule status

Agregar Nuevos Submodules

Para agregar un nuevo repositorio externo como referencia:

# Ejemplo: agregar un nuevo repo en reference
git submodule add --depth 1 https://github.com/user/repo.git knowledge-base/reference/nombre-repo

# Ejemplo: agregar en catalog
git submodule add --depth 1 https://github.com/user/repo.git core/catalog/nombre-modulo

Política de Submodules

Los submodules se usan para:

• Código de referencia externo (knowledge-base/reference/)
• Módulos del catálogo que vienen de repos externos (core/catalog/)

Importante: Los submodules mantienen su propio historial git y se sincronizan con el repo original.

Estrategia de Gitignore

Nivel Workspace (/.gitignore)

El archivo maestro .gitignore en la raíz excluye:

Categoría	Exclusiones
Dependencias	**/node_modules/, **/.venv/, **/venv/
Build	**/dist/, **/build/, **/.next/, **/.turbo/
Testing	**/coverage/, **/.pytest_cache/
Secrets	**/.env*, **/credentials.json, **/*.pem
Database	**/*.dump, **/*.backup, **/pgdata/
IDE	**/.idea/, **/.vscode/* (excepto settings compartidos)
OS	**/.DS_Store, **/Thumbs.db
Logs	**/*.log, **/logs/
i18n/Traducciones	**/i18n/*.po, **/i18n/*.pot (archivos de traducción pesados)
Fuentes	**/*.woff, **/*.ttf, **/*.eot (fuentes tipográficas)

Nivel Proyecto

Cada proyecto puede tener su propio .gitignore para exclusiones específicas.

Templates disponibles en /devtools/templates/gitignore/:

• .gitignore.project.template - Template general para proyectos
• .gitignore.backend.template - Template para apps backend
• .gitignore.frontend.template - Template para apps frontend
• .gitignore.database.template - Template para carpetas database

Configurar Repositorio Independiente por Proyecto

Opción 1: Git Subtree (Recomendado)

Permite mantener proyectos como parte del workspace principal pero con repositorios independientes.

# En el proyecto que quieres independizar
cd /home/isem/workspace/projects/gamilit

# Agregar como subtree desde el workspace
git subtree add --prefix=projects/gamilit git@github.com:user/gamilit.git main --squash

# Push cambios al repo independiente
git subtree push --prefix=projects/gamilit git@github.com:user/gamilit.git main

# Pull cambios del repo independiente
git subtree pull --prefix=projects/gamilit git@github.com:user/gamilit.git main --squash

Opción 2: Git Submodule

Para proyectos que deben ser completamente independientes.

# Desde el workspace raíz
git submodule add git@github.com:user/gamilit.git projects/gamilit

# Clonar workspace con submodules
git clone --recurse-submodules git@github.com:rckrdmrd/workspace.git

# Actualizar submodules
git submodule update --remote --merge

Opción 3: Repositorios Separados con Links Simbólicos

Para desarrollo local con repos completamente separados.

# Estructura real fuera del workspace
~/repos/gamilit/  # Repo independiente

# Link simbólico en el workspace
ln -s ~/repos/gamilit /home/isem/workspace/projects/gamilit

Nota: Los links simbólicos NO se versionan en git por defecto.

Estructura de Niveles

workspace/                          # NIVEL 0 - Workspace
├── projects/
│   ├── [plataforma]/               # NIVEL 1 - Plataforma (ej: erp-suite)
│   │   ├── apps/
│   │   │   ├── [subplataforma]/    # NIVEL 2 - Subplataforma (ej: verticales)
│   │   │   │   └── [proyecto]/     # NIVEL 3 - Proyecto (ej: construccion)
│   │   │   │       ├── backend/    # NIVEL 4 - Componente
│   │   │   │       ├── frontend/   # NIVEL 4 - Componente
│   │   │   │       └── database/   # NIVEL 4 - Componente

Repositorios por Nivel

Nivel	Ejemplo	Puede tener repo independiente
0	workspace	Sí (este repositorio)
1	erp-suite, gamilit	Sí
2	verticales, saas	Opcional
3	construccion, clinicas	Sí
4	backend, frontend	Raramente necesario

Flujo de Trabajo Recomendado

Desarrollo Normal (Solo workspace)

# Trabajar normalmente
git add .
git commit -m "feat: descripción del cambio"
git push origin main

Con Repositorios por Proyecto (Subtree)

# 1. Commit en workspace
git add .
git commit -m "feat: cambios en gamilit"
git push origin main

# 2. Sincronizar con repo del proyecto
git subtree push --prefix=projects/gamilit git@github.com:user/gamilit.git main

Clonar Workspace Completo

# Clone básico
git clone https://github.com/rckrdmrd/workspace.git

# Si usa submodules
git clone --recurse-submodules https://github.com/rckrdmrd/workspace.git

Archivos y Carpetas que SÍ se Versionan

• Código fuente (TypeScript, JavaScript, Python, etc.)
• Documentación (/docs, /orchestration, /core)
• Configuraciones compartidas (.vscode/settings.json, tsconfig.json)
• Scripts de desarrollo (/devtools/scripts)
• Templates y patrones (/core/catalog, /devtools/templates)
• DDL y migrations (/database/ddl, /database/migrations)
• Seeds de ejemplo (/database/seeds - solo datos de ejemplo)
• Archivos de configuración ejemplo (.env.example)

Archivos que NUNCA se Versionan

• Dependencias (node_modules/, venv/)
• Archivos compilados (dist/, build/)
• Datos sensibles (.env, credentials.json)
• Datos de clientes
• Backups de base de datos
• Logs
• Archivos grandes de referencia (knowledge-base/reference/odoo/)

Comandos Útiles

# Ver estado del repositorio
git status

# Ver archivos ignorados
git status --ignored

# Ver qué archivos serían trackeados
git ls-files

# Verificar tamaño del repositorio
git count-objects -vH

# Ver estructura de remotos
git remote -v

# Listar branches
git branch -a

Migración del Workspace

Para migrar el workspace a otra máquina:

# 1. Clonar repositorio
git clone https://github.com/rckrdmrd/workspace.git
cd workspace

# 2. (Opcional) Si usa submodules
git submodule update --init --recursive

# 3. Instalar dependencias por proyecto
cd projects/gamilit && npm install
cd ../trading-platform && npm install
# etc.

Contacto y Mantenimiento

El repositorio principal es mantenido en:

• GitHub: https://github.com/rckrdmrd/workspace.git