soleprint/mainroom/link

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:

{
  "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

# 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