chore(issues): plan 0049 OSINT graph viewer multi-issue
Aggregates the planning artifacts for the 0049 series (umbrella + 0049a..0049k): - New rule cpp_apps.md (registered in INDEX) — standardize structure, CMake patterns, app.md frontmatter and sub-repo for C++ apps; points to the authoritative cpp/PATTERNS.md and cpp/DESIGN_SYSTEM.md. - Feature flag osint_graph_v1 (disabled until 0049k closes). - Issue 0049 (umbrella) and sub-issues 0049b..0049k describing the GPU rendering system, force-layout, types, sources, labels and the final graph_explorer app integration. - README updated with the new rows (all pending; 0049a will flip to completed in the next commit).
This commit is contained in:
@@ -0,0 +1,168 @@
|
||||
# 0049 — OSINT graph viewer + GPU graph rendering system
|
||||
|
||||
## Metadata
|
||||
|
||||
| Campo | Valor |
|
||||
|-------|-------|
|
||||
| **ID** | 0049 |
|
||||
| **Estado** | pendiente |
|
||||
| **Prioridad** | alta |
|
||||
| **Tipo** | feature — proyecto C++ multi-fase |
|
||||
|
||||
## Dependencias
|
||||
|
||||
| ID | Título | Estado | Requerido |
|
||||
|----|--------|--------|-----------|
|
||||
| 0042 | C++ layout_storage publico | completado | si |
|
||||
| 0043 | C++ apps standardize shell | completado | si |
|
||||
| 0048 | C++ visual tests CI gate | completado | si |
|
||||
|
||||
**Bloqueada por:** ninguna (todas las deps cerradas).
|
||||
**Desbloquea:** apps tipo Maltego local + cualquier app del registry que necesite visualizacion de grafos a escala.
|
||||
|
||||
---
|
||||
|
||||
## Objetivo
|
||||
|
||||
Construir un **sistema de visualizacion de grafos GPU-accelerated, agnostico del backend de datos**, y sobre el una app `graph_explorer` para OSINT/ontologia. El renderer debe escalar a 50k+ nodos sin caida de fps, soportar layouts (force, grid, circular, radial, jerarquico, fixed), formas/iconos/colores per-tipo, edges direccionales y con estilos, drag-and-drop, multiseleccion, labels con politica, y filtros por tipo. Datos cargables desde `operations.db` de cualquier app del registry como primer source, con abstraccion funcional preparada para JSON/JSONL/GraphML.
|
||||
|
||||
## Contexto
|
||||
|
||||
**Lo que existe hoy** (`cpp/functions/viz/`):
|
||||
- `graph_renderer` — instanced quad rendering en OpenGL 3.3 con SDF circular. CPU rebuilds vertex buffers cada frame.
|
||||
- `graph_force_layout` — Barnes-Hut quadtree en CPU, una iteracion por frame.
|
||||
- `graph_viewport` — wrapper ImGui con pan/zoom/hit-testing.
|
||||
- `graph_types` — `GraphNode`/`GraphEdge` minimos.
|
||||
|
||||
**Lo que limita escalar:**
|
||||
1. Force layout en CPU domina a partir de ~5k nodos.
|
||||
2. Renderer aloca y resube buffers cada frame (`glBufferData`).
|
||||
3. Aristas reconstruidas vertex-by-vertex en CPU.
|
||||
4. Sin shapes, iconos, edge styles, flechas, filtros, labels.
|
||||
5. Bound a OpenGL 3.3 (sin compute shaders ni SSBOs).
|
||||
|
||||
**Caso de uso final:**
|
||||
Visor tipo Maltego local con extraccion de entidades por tipos sobre `analysis/ontology_graph` (OSINT banca espanola, ya en marcha). Recoleccion masiva → entities/relations llegan en streaming → visualizacion en tiempo real.
|
||||
|
||||
## Arquitectura
|
||||
|
||||
```
|
||||
projects/osint_graph/ # NEW project
|
||||
├── project.md # NEW
|
||||
├── apps/
|
||||
│ └── graph_explorer/ # NEW app (sub-repo dataforge/graph_explorer)
|
||||
│ ├── app.md
|
||||
│ ├── CMakeLists.txt
|
||||
│ ├── main.cpp
|
||||
│ ├── data.{h,cpp} # dispatcher de GraphLoadFn
|
||||
│ ├── views.{h,cpp} # toolbar/legend/inspector/stats
|
||||
│ └── types_registry.{h,cpp} # carga types.yaml para visual override
|
||||
├── analysis/ # vacio inicial
|
||||
└── vaults/
|
||||
└── osint_data -> ~/vaults/osint_graph/ # symlink
|
||||
|
||||
cpp/functions/viz/ # extensiones + funciones nuevas
|
||||
├── graph_types.{h,cpp} # MOD — modelo extendido (type_id, flags, icons...)
|
||||
├── graph_renderer.{h,cpp} # MOD — RGBA8, orphan, TBO, shapes, iconos, flechas
|
||||
├── graph_force_layout.{h,cpp} # MOD — auto-pause
|
||||
├── graph_force_layout_gpu.{h,cpp} # NEW — compute shader + spatial hash
|
||||
├── graph_layouts.{h,cpp} # NEW — radial, hierarchical, fixed (consolida)
|
||||
├── graph_viewport.{h,cpp} # MOD — lasso, multi-select, drag-pin, callbacks
|
||||
├── graph_labels.{h,cpp} # NEW — render con LabelPolicy
|
||||
├── graph_icons.{h,cpp} # NEW — atlas Tabler en textura
|
||||
└── graph_sources.{h,cpp} # NEW — graph_load_from_operations + stream
|
||||
|
||||
cpp/framework/app_base.cpp # MOD — bump GL 3.3 → 4.3 core
|
||||
|
||||
.claude/rules/cpp_apps.md # YA AÑADIDO en sesion previa
|
||||
```
|
||||
|
||||
### Abstraccion funcional `GraphSource`
|
||||
|
||||
Misma firma para todos los backends — swap por puntero a funcion, sin virtuals:
|
||||
|
||||
```cpp
|
||||
typedef bool (*GraphLoadFn)(const char* uri, GraphData* out, GraphLoadStats* stats);
|
||||
|
||||
bool graph_load_from_operations(const char*, GraphData*, GraphLoadStats*);
|
||||
bool graph_load_from_json (const char*, GraphData*, GraphLoadStats*); // futuro
|
||||
bool graph_load_from_jsonl (const char*, GraphData*, GraphLoadStats*); // futuro
|
||||
bool graph_load_from_graphml (const char*, GraphData*, GraphLoadStats*); // futuro
|
||||
|
||||
struct GraphStreamSource;
|
||||
GraphStreamSource* graph_stream_operations_open(const char* db_path, int poll_ms);
|
||||
int graph_stream_pull(GraphStreamSource*, GraphData*);
|
||||
void graph_stream_close(GraphStreamSource*);
|
||||
```
|
||||
|
||||
## Desglose multi-issue
|
||||
|
||||
Este issue se implementa en 11 sub-issues independientes. Cada sub-issue es autocontenido — debe compilar, pasar tests, no romper master. Trunk-based development obligatorio (ver `.claude/rules/apps_tbd.md`).
|
||||
|
||||
| Sub-issue | Rama | Alcance | Estado |
|
||||
|-----------|------|---------|--------|
|
||||
| [0049a](0049a-osint-graph-setup.md) | issue/0049a-osint-graph-setup | Crear proyecto `osint_graph` + vault + sub-repo Gitea de la app | pendiente |
|
||||
| [0049b](0049b-cpp-bump-gl-43.md) | issue/0049b-cpp-bump-gl-43 | Bump OpenGL 3.3 → 4.3 core en `app_base` + verificar apps existentes | pendiente |
|
||||
| [0049c](0049c-graph-renderer-tier1.md) | issue/0049c-graph-renderer-tier1 | RGBA8, orphan buffers, frustum cull aristas, auto-pause force | pendiente |
|
||||
| [0049d](0049d-graph-edges-vertex-pulling.md) | issue/0049d-graph-edges-vertex-pulling | TBO + vertex pulling para aristas | pendiente |
|
||||
| [0049e](0049e-graph-types-extended.md) | issue/0049e-graph-types-extended | Modelo extendido: type_id, flags, EntityType/RelationType | pendiente |
|
||||
| [0049f](0049f-graph-renderer-symbols.md) | issue/0049f-graph-renderer-symbols | Shapes SDF, icon atlas, flechas, edge styles | pendiente |
|
||||
| [0049g](0049g-graph-source-operations.md) | issue/0049g-graph-source-operations | `graph_load_from_operations` + stream variant | pendiente |
|
||||
| [0049h](0049h-graph-force-layout-gpu.md) | issue/0049h-graph-force-layout-gpu | Compute shader + spatial hash GPU | pendiente |
|
||||
| [0049i](0049i-graph-layouts-static.md) | issue/0049i-graph-layouts-static | radial, hierarchical, fixed + viewport extendido | pendiente |
|
||||
| [0049j](0049j-graph-labels.md) | issue/0049j-graph-labels | `graph_labels` con LabelPolicy via ImDrawList | pendiente |
|
||||
| [0049k](0049k-graph-explorer-app.md) | issue/0049k-graph-explorer-app | App `graph_explorer` + indexado + push final | pendiente |
|
||||
|
||||
### Feature flag
|
||||
|
||||
Nombre: `osint_graph_v1`
|
||||
Se activa al cerrar `0049k` cuando `graph_explorer` compila, consume operations.db y muestra grafos OSINT con todas las features (shapes, iconos, layouts, labels, filtros).
|
||||
|
||||
### Progreso por fase
|
||||
|
||||
- [ ] **0049a** — proyecto osint_graph + vault + sub-repo
|
||||
- [ ] **0049b** — bump GL 4.3
|
||||
- [ ] **0049c** — renderer Tier 1 (perf)
|
||||
- [ ] **0049d** — edges via vertex pulling (perf)
|
||||
- [ ] **0049e** — modelo de datos extendido (breaking change a graph_types)
|
||||
- [ ] **0049f** — shapes/iconos/edge-styles/flechas (renderer extendido)
|
||||
- [ ] **0049g** — source operations.db + streaming
|
||||
- [ ] **0049h** — force layout GPU compute
|
||||
- [ ] **0049i** — layouts estaticos + viewport extendido
|
||||
- [ ] **0049j** — labels con politica
|
||||
- [ ] **0049k** — app graph_explorer + flag activado
|
||||
|
||||
## Decisiones de diseno
|
||||
|
||||
1. **OpenGL 4.3 core** (no 3.3): habilita compute shaders + SSBOs, simplifica el layout GPU drasticamente. Trade: GPUs ~2012+ obligatorias (todas las modernas — aceptable).
|
||||
2. **Spatial hash grid GPU** en vez de Barnes-Hut: Barnes-Hut quadtree es muy duro en GPU sin punteros. Spatial hash es uniforme en carga y suficiente visualmente para el caso OSINT.
|
||||
3. **Modelo de datos extendido es breaking change** controlado: la unica consumidora actual es `demos_graph` en `primitives_gallery`; se migra en el mismo sub-issue (0049e).
|
||||
4. **GraphSource es funcional, no OO**: punteros a funcion con misma firma, swap trivial. Sin virtuals, sin templates, sin std::function en hot path.
|
||||
5. **types.yaml externo** define visual mapping (color/shape/icon per entity type). El renderer no sabe nada de OSINT — solo lee tablas.
|
||||
6. **CPU mirror de posiciones** se mantiene siempre (8 bytes × N) para hit-test, drag, labels — leido via `glGetBufferSubData` 1x/frame. Trivial coste, simplifica todo.
|
||||
7. **Cada app C++ es sub-repo Gitea** (`apps_tbd.md` + `cpp_apps.md`): `graph_explorer` se crea con `.git` apuntando a `dataforge/graph_explorer`.
|
||||
|
||||
## Riesgos
|
||||
|
||||
| Riesgo | Mitigacion |
|
||||
|---|---|
|
||||
| Bump GL 4.3 rompe apps existentes en HW antiguo | Validar en 0049b sobre las 4 apps actuales en Linux + Windows cross-compile antes de mergear |
|
||||
| Compute shader complexity (0049h) | Caer back a CPU layout es trivial — la API es identica |
|
||||
| Streaming desde operations.db sin estabilidad de positions | Pin nodos nuevos cerca del padre por N frames, luego release |
|
||||
| Demo `demos_graph` queda roto durante 0049e | Migrar `demos_graph.cpp` en el mismo sub-issue con tests visuales |
|
||||
| Atlas de iconos Tabler ocupa espacio | 512×512 RGBA = 1 MB en VRAM, despreciable |
|
||||
|
||||
## Criterio de done global
|
||||
|
||||
- [ ] `graph_explorer` abre cualquier `apps/<x>/operations.db` del registry y lo visualiza con tipos descubiertos automaticamente.
|
||||
- [ ] 50k nodos + 200k aristas a 60fps en GPU integrada con layout corriendo.
|
||||
- [ ] Drag, multi-select (Ctrl+click + Shift+lasso), filter-by-type, fit-view operativos.
|
||||
- [ ] Labels visibles para selected/hovered + top-N por tamaño con LabelPolicy configurable.
|
||||
- [ ] Iconos Tabler renderizados dentro de cada nodo segun `EntityType.icon_id`.
|
||||
- [ ] Edges direccionales con flechas + estilos solid/dashed/dotted segun `RelationType.style`.
|
||||
- [ ] `types.yaml` opcional que mergea defaults con override visual por tipo.
|
||||
- [ ] `fn index` completa y todas las funciones nuevas aparecen con `uses_functions` correcto.
|
||||
- [ ] Tests Catch2 verdes para `graph_layouts`, `graph_icons`, `graph_force_layout_gpu`, `graph_sources`.
|
||||
- [ ] Visual test golden actualizado para `demos_graph` con el nuevo modelo.
|
||||
- [ ] Sub-repo `dataforge/graph_explorer` pushed con master limpio.
|
||||
- [ ] Feature flag `osint_graph_v1` = `true`.
|
||||
Reference in New Issue
Block a user