fn_registry/.claude/rules/projects.md

Projects: apps, analysis y vaults bajo un tema comun

Un project agrupa apps, analyses y vaults relacionados. Vive en projects/{nombre}/ con esta estructura:

projects/{nombre}/
  project.md                    # Frontmatter obligatorio (name, description, tags)
  apps/                         # Apps del proyecto (cada una con app.md)
    {app_name}/
      app.md
      ...
  analysis/                     # Analyses del proyecto (cada uno con analysis.md)
    {analysis_name}/
      analysis.md
      .venv/
      notebooks/
      run-jupyter-lab.sh
      ...
  vaults/                       # Datos del proyecto
    vault.yaml                  # Manifest de vaults (nombre, descripcion, path, tags)
    {vault_name} -> /abs/path   # Symlinks a directorios reales de datos

Reglas

• project.md sigue el template de docs/templates/project.md — campos: name, description, tags, repo_url
• analysis.md sigue el template de docs/templates/analysis.md — dir_path debe apuntar a projects/{nombre}/analysis/{tema}/
• vault.yaml lista los vaults con nombre, descripcion, path absoluto y tags
• Los vaults reales viven fuera del repo (ej: ~/vaults/{nombre}/) con symlinks en el proyecto
• fn index escanea projects/*/ y setea project_id automaticamente en apps, analyses y vaults

Cada project es su propio repo Gitea (sub-repo)

Desde 2026-06-05 cada projects/<nombre>/ es un repo Gitea independiente dataforge/<nombre> (branch master), igual que las apps y los analyses. El repo del project versiona solo las docs de nivel-project (project.md, CONVENTIONS.md y demás .md/.claude/ propios del project). El contenido de los hijos NO se versiona aquí: cada apps/<app>/ y cada analysis/<a>/ es su propio sub-repo Gitea y queda excluido por el .gitignore del project:

apps/*/
analysis/*/
vaults/*
!vaults/.gitkeep

• Crear el repo del project: ensure_repo_synced_bash_infra projects/<nombre> dataforge <nombre> master "init: project <nombre>" (necesita GITEA_URL + GITEA_TOKEN; el token está en pass gitea/dataforge-git-token). Crear el .gitignore de arriba ANTES, para no trackear el contenido de los sub-repos hijos.
• Push/pull: /full-git-push y /full-git-pull ya lo manejan automáticamente — discover_git_repos_bash_infra descubre cualquier .git bajo fn_registry, incluidos los projects.
• repo_url en project.md apunta al repo del project; los repo_url de cada app viven en su app.md. Así el project "referencia" sus sub-repos sin git submodules (KISS).
• El repo padre fn_registry sigue ignorando projects/*/ entero (regla apps_subrepo.md): nunca trackea contenido de projects.
• Estado actual: dataforge/web_scraping, dataforge/fn_monitoring, dataforge/message_bus.
• Apps y analyses sueltos (sin proyecto) siguen en apps/ y analysis/ en la raiz

Raiz vs proyecto

Ubicacion	Para que
apps/	Apps independientes que no pertenecen a ningun proyecto
analysis/	Analyses independientes
projects/{nombre}/apps/	Apps de un proyecto — project_id se setea automaticamente
projects/{nombre}/analysis/	Analyses de un proyecto — project_id se setea automaticamente

Crear un proyecto nuevo

# 1. Crear estructura
mkdir -p projects/{nombre}/{apps,analysis,vaults}

# 2. Crear project.md con frontmatter
fn add -k project  # genera template

# 3. Crear vault (datos fuera del repo, symlink dentro)
mkdir -p ~/vaults/{vault_name}/{raw,processed,exports}
ln -s ~/vaults/{vault_name} projects/{nombre}/vaults/{vault_name}
# Crear vault.yaml con la entrada

# 4. Crear analysis dentro del proyecto (un solo comando; ya indexa)
fn run init_jupyter_analysis --project {nombre} {nombre_analysis} --desc "..." [paquetes...]

# 5. Verificar
fn show {nombre}  # verifica el project y sus componentes

# NUNCA: crear el analisis en analysis/ y luego mv al proyecto.
# Al mover se rompe el .venv (paths hardcodeados en activate).
# Si ya te paso: cd projects/{nombre}/analysis/{tema} && rm -rf .venv && uv sync

Consultas utiles

-- Listar proyectos
SELECT id, description FROM projects;

-- Analysis de un proyecto
SELECT id, name, dir_path FROM analysis WHERE project_id = 'app_turismo';

-- Vaults de un proyecto
SELECT id, name, path, symlink FROM vaults WHERE project_id = 'app_turismo';

-- Apps de un proyecto
SELECT id, name, dir_path FROM apps WHERE project_id = 'app_turismo';

-- Todo lo que pertenece a un proyecto
SELECT 'analysis' as tipo, id, name FROM analysis WHERE project_id = ?
UNION ALL
SELECT 'vault', id, name FROM vaults WHERE project_id = ?
UNION ALL
SELECT 'app', id, name FROM apps WHERE project_id = ?;