fn_registry/docs/architecture.md

Arquitectura del sistema

---

Dos bases de datos, dos propósitos

	Registry (esta BBDD)	Operacional (por proyecto)
Qué almacena	Lo que sabes hacer	Lo que has hecho y cómo fluye
Naturaleza	Conocimiento estático	Conocimiento dinámico
Cuándo cambia	Solo al añadir código	En cada proyecto activo
Scope	Compartida entre todos los proyectos	Local a cada proyecto
Tablas	functions, types	entities, relations

---

Registry — estructura de directorios

fn-registry/
  functions/
    core/
      filter_slice.go
      filter_slice.md
    finance/
      parse_ohlcv.go
      parse_ohlcv.md
    io/
      fetch_ticks.go
      fetch_ticks.md
    pipelines/
      tick_to_ohlcv.go
      tick_to_ohlcv.md
    components/
      DataTable.tsx
      DataTable.md
  types/
    core/
      result.go
      result.md
    finance/
      ohlcv.go
      ohlcv.md
  registry.db       ← SQLite, solo índice FTS. Regenerable siempre.
  fn                ← binario CLI

Los archivos .go / .tsx son la fuente de verdad del código. Los archivos .md son la fuente de verdad de la documentación. registry.db es solo el índice — si se borra, fn index lo regenera en segundos.

---

CLI — comandos

fn search "filter predicate sin mutar"   # búsqueda FTS sobre nombre, descripción, tags, signature
fn search -k function -p pure "slice"    # filtrar por kind y purity
fn search -l go -d finance "ohlcv"       # filtrar por lang y domain
fn search -k component "tabla datos"     # buscar componentes React

fn add                                   # abre $EDITOR con template según kind
fn show filter_slice_go_core             # imprime entrada completa
fn index                                 # regenera registry.db desde los .md

fn list                                  # lista todas las entradas
fn list -d finance                       # lista por dominio
fn list -k pipeline                      # lista solo pipelines

---

Operacional — tablas por proyecto

Cada proyecto tiene su propia BBDD operacional que referencia IDs del registry.

Entities

Instancias concretas de tipos registrados dentro de un contexto de ejecución.

Campo	Tipo	Descripción
id	string	Identificador único
name	string	Nombre semántico (ticks_btcusdt)
type_ref	string	Referencia al types.id del registry
description	text	Qué representa en este dominio concreto
tags	[]string	Etiquetas

Relations

Cómo las entidades se conectan a través de funciones o pipelines.

Campo	Tipo	Descripción
id	string	Identificador único
from_entity	string	Entidad origen
to_entity	string	Entidad destino
via	string	functions.id que transforma
description	text	Qué ocurre en esta transformación
purity	enum	pure | impure

---

El agente y el registry

El agente consulta el registry para:

1. Descubrir qué funciones y tipos existen en un dominio
2. Razonar sobre composabilidad comparando returns con uses_types
3. Priorizar funciones puras para el núcleo del pipeline
4. Aislar impuras en los bordes
5. Verificar que los contratos no están rotos comparando version

El agente consulta la operacional para:

1. Entender qué entidades fluyen en este proyecto concreto
2. Ver qué transformaciones ya están modeladas
3. Detectar patrones de uso frecuentes

---

Capa diagnostica: fn doctor

Sobre el modelo registry+operations existe el comando fn doctor (read-only) que reporta estado del sistema:

• artefacts — salud por artefacto (git/venv/manifest/upstream).
• services — apps tag service + systemctl + puerto.
• sync — drift pc_locations BD vs disco del PC actual.
• uses-functions — drift entre imports reales en codigo de apps y uses_functions declarado en app.md.
• unused — funciones del registry sin consumidores.

Cada subcomando es wrapper fino sobre una funcion del registry (functions/infra/{artefact_doctor,services_status,pc_locations_drift,audit_uses_functions,find_unused_functions}.go). La logica vive en el registry; el CLI solo formatea. --json produce salida estructurada para agentes. Detalle en .claude/rules/fn_doctor.md.

Util tras deploys, fn sync, git pull masivos o como gate antes de evaluar metricas del bucle reactivo.

---

Mejoras incorporadas al schema v1.0

Problema	Solución
IDs frágiles con colisiones	Formato {name}_{lang}_{domain} + UUID interno
lang libre fragmenta el índice	Enum controlado, normalizado al indexar
Sin versionado	Campo version semver en functions y types
file_path absoluta se rompe al mover	Siempre relativa a la raíz del registry
Sin contexto de dominio	Campo domain obligatorio
Sin trazabilidad temporal	created_at / updated_at automáticos
signature ambigua en lenguajes dinámicos	Convención formal definida para Python/SQL
Pura que devuelve opcional mal modelada	Regla: modelar como tipo suma, no returns_optional: true