migrated core_nest to mainroom

2025-12-24 06:23:31 -03:00
parent 329c401ff5
commit d62337e7ba
50 changed files with 5503 additions and 73 deletions
--- a/mainroom/link/README.md
+++ b/mainroom/link/README.md
@@ -0,0 +1,120 @@
+# Link Nest - Adapter Layer
+
+Provides framework-agnostic data navigation between managed apps (AMAR) and pawprint.
+
+## Status: Initial Implementation ✅
+
+**Working:**
+- ✅ FastAPI service with adapter pattern
+- ✅ BaseAdapter interface for pluggable frameworks
+- ✅ DjangoAdapter with AMAR database queries
+- ✅ Docker build and container starts
+- ✅ `/health` endpoint (adapter loads successfully)
+- ✅ `/api/queries` endpoint (lists available queries)
+
+**Pending:**
+- ⏳ Database connection (needs DB_HOST env var fix)
+- ⏳ Complete all entity queries (Pet, Vet, ServiceRequest, etc.)
+- ⏳ Ward integration (consume JSON and render graph)
+
+## Architecture
+
+```
+Managed App (AMAR) ←─── link_nest ───→ Pawprint (Ward)
+      ↓                     ↓                  ↓
+   Database         Adapter Layer      Graph Renderer
+                    (SQL → JSON)        (JSON → SVG)
+```
+
+**JSON Contract:**
+```json
+{
+  "nodes": [
+    {"id": "User_123", "type": "User", "label": "john", "data": {...}}
+  ],
+  "edges": [
+    {"from": "User_123", "to": "PetOwner_456", "label": "has profile"}
+  ],
+  "summary": {
+    "title": "User #123",
+    "credentials": "john | Password: Amar2025!",
+    "fields": {"Email": "john@example.com"}
+  }
+}
+```
+
+## Endpoints
+
+- `GET /health` - Health check with adapter status
+- `GET /api/queries` - List available predefined queries
+- `GET /api/navigate?query=user_with_pets` - Query mode
+- `GET /api/navigate?entity=User&id=123` - Entity navigation mode
+
+## Available Queries
+
+1. `user_with_pets` - User with Pet ownership
+2. `user_with_requests` - User with ServiceRequests
+
+## Usage
+
+```bash
+# Start (from core_nest/ctrl)
+./start.sh link_nest -d --build
+
+# Test
+curl http://localhost:8100/health
+curl http://localhost:8100/api/queries
+curl "http://localhost:8100/api/navigate?query=user_with_pets"
+
+# Logs
+docker logs core_nest_link_nest
+```
+
+## Environment Variables
+
+From `core_nest/.env`:
+- `NEST_NAME` - Container naming
+- `NETWORK_NAME` - Docker network
+- `DB_HOST` - Database host (needs fix: should point to db container)
+- `DB_PORT` - Database port
+- `DB_NAME` - Database name
+- `DB_USER` - Database user
+- `DB_PASSWORD` - Database password
+- `ADAPTER_TYPE` - Adapter to use (default: django)
+
+## Next Steps
+
+1. **Fix DB connection** - Set correct DB_HOST in core_nest/.env
+2. **Complete queries** - Add remaining entity types
+3. **Ward integration** - Create ward consumer for JSON
+4. **Add graphviz rendering** - Move from data_browse reference
+5. **Test end-to-end** - Query → JSON → SVG → Display
+
+## Files
+
+```
+link_nest/
+├── README.md              # This file
+├── main.py                # FastAPI app with endpoints
+├── requirements.txt       # Python dependencies
+├── Dockerfile             # Container build
+├── docker-compose.yml     # Service definition
+└── adapters/
+    ├── __init__.py        # BaseAdapter interface
+    └── django.py          # DjangoAdapter implementation
+```
+
+## Design Goals
+
+✅ **Framework-agnostic** - Works with Django, Rails, Express, etc.
+✅ **Decoupled** - Managed app owns data, link_nest translates
+✅ **Pluggable** - Adapters for different frameworks
+✅ **Authenticated** - Ready for remote deployment
+✅ **Incremental** - Build and test each piece
+
+## Reference
+
+Previous approach (databrowse direct DB) saved in:
+- Branch: `ref/databrowse-direct-db` (ward repo)
+- Problem: Tight coupling, won't work remote
+- Solution: This adapter pattern