jpmschweitzerandClaude Opus 4.5
1a41e5bb80
Implements comprehensive service client layer for Library Desk API to support
Librarian AI agent with multi-tenant knowledge management across Neo4j, Qdrant,
Wiki.js, SearXNG, and Ollama.
## Service Clients (src/clients/)
- Neo4j async client with connection pooling and user-scoped labels
- Qdrant vector store with collection-per-user multi-tenancy
- Wiki.js GraphQL API client for page/dossier management
- SearXNG client for web search integration
- Ollama client for text embeddings (nomic-embed-text)
## Core Infrastructure (src/core/)
- Multi-tenancy helpers for user namespace management
- Wiki.js: path-based namespaces (/users/{user})
- Neo4j: user-specific labels (User_{User}_Document)
- Qdrant: collection per user (library_desk_{user})
- Dependency injection with FastAPI Depends and @lru_cache singletons
- Lifecycle management (startup/shutdown) for all service connections
## Background Jobs (src/jobs/)
- Redis-based job manager for long-running operations
- Job status tracking with 24-hour TTL
- Support for queued, processing, completed, failed states
## Configuration
- Updated config.py with Redis DB 4 for library-desk jobs
- Updated docker-compose.yml: REDIS_DB from 2 to 4
- Added pytest and pytest-asyncio to requirements.txt
## Testing
- Unit tests: 25/25 passed (multi-tenancy helpers)
- Integration tests: 12/12 passed (all services verified)
- Neo4j connection and CRUD operations
- Qdrant vector operations with 768-dim embeddings
- Wiki.js GraphQL queries
- SearXNG web search
- Job Manager with Redis
- Dependency injection lifecycle
- pytest.ini configuration with asyncio support
## Health Monitoring
- Real-time service health checks via /health endpoint
- Connection status for all 5 external services
- Graceful degradation for partial service availability
## Architecture
- Follows async/await pattern throughout
- Connection pooling for Neo4j (singleton driver)
- HTTP client lifecycle management (httpx)
- Multi-tenancy enforced at client layer
- Default user: jpmschweitzer
Files changed: 26 files
- 5 new service clients (~1500 lines)
- 2 core modules (~500 lines)
- 1 job manager (~350 lines)
- 3 test files with 37 test cases
- Updated main.py with lifecycle hooks
All services tested and operational. Ready for Phase 2 (routers/services).
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
portainer-core
Self-hosted home server infrastructure with GPU-accelerated ML, AI orchestration, media streaming, and secure remote access
Main Dashboard: https://home.schweitz.net (Organizr)
Quick Links
Getting Started
- System Specifications - Hardware and software details
- Container Reference - All deployed services
- Current Status - Implementation progress and phase tracking
Implementation Plans
- Implementation Plans - Master plan tracker
- Active Plans - Current development work
- Completed Plans - Historical implementations
Documentation Index
Architecture & Design
- Shared Infrastructure Architecture - PostgreSQL/Redis shared infrastructure
Operational Guides
- Backup Procedures - Backup strategies and procedures
- Code-Server Setup - Browser-based IDE configuration
- Connect Devices Guide - Headscale VPN setup
- GPU Docker Configuration - NVIDIA GPU passthrough
- Headscale Setup - Mesh VPN deployment
- NPM Logging Guide - Nginx Proxy Manager logging
Services
- Core API - Infrastructure management and AI orchestration
- Organizr Widgets - Service control dashboard
Reference
- Stacks Reference - All Docker Compose stacks
- Scripts Reference - Maintenance automation
- Automation Reference - Portainer REST API usage
- Container Reference - Complete container profiles
- System Reference - Hardware specifications
- Changelog - Version history
For AI Agents
- Agent Guidelines - REQUIRED READING for all LLM coding agents
Architecture Overview
┌─────────────────────────────────────────┐
│ Infrastructure Layer │
│ ├── Portainer (8080) - Container mgmt │
│ ├── PostgreSQL Shared (5432) - DB │
│ ├── Redis Shared (6379) - Cache │
│ ├── NPM (8000) - Reverse proxy │
│ └── Ollama (11434) - ML models [GPU] │
├─────────────────────────────────────────┤
│ Networking Layer │
│ ├── docker-dataplane - Service mesh │
│ └── Headscale (8085) - VPN mesh │
├─────────────────────────────────────────┤
│ Monitoring Layer │
│ ├── Uptime Kuma (3001) - Uptime │
│ ├── Netdata (19999) - Metrics │
│ └── Organizr (8084) - Dashboard │
├─────────────────────────────────────────┤
│ Optimization Layer │
│ ├── Watchtower - Auto-updates │
│ └── Maintenance - Automated backups │
├─────────────────────────────────────────┤
│ Application Layer │
│ ├── Open WebUI (8081) - LLM chat UI │
│ ├── Core API (8083) - Infra mgmt │
│ ├── Jellyfin (8096) - Media [GPU] │
│ ├── Nextcloud (8082) - Cloud storage │
│ ├── Gitea (3002) - Git hosting │
│ └── Samba (445) - File shares │
└─────────────────────────────────────────┘
Project Structure
portainer-core/
├── plans/ # Implementation plans
│ ├── active/ # Current development work
│ └── completed/ # Historical implementations
├── docs/ # Documentation
│ ├── architecture/ # Design documents
│ ├── guides/ # Setup and operational guides
│ ├── services/ # Service-specific documentation
│ └── reference/ # Quick reference materials
├── stacks/ # Docker Compose files (version-controlled)
├── scripts/ # Maintenance automation
├── services/ # Service source code
│ ├── core-api/ # Infrastructure management API
│ └── ...
├── organizr-widgets/ # Dashboard widgets
├── AGENTS.md # AI agent guidelines (single source of truth)
├── README.md # This file (documentation index)
├── PLANS.md # Implementation plan tracker
├── STATUS.md # Current phase tracking
└── CHANGELOG.md # Version history
Common Commands
Infrastructure Management
make status # Show running containers and system status
make health # Comprehensive health check
make gpu-check # Verify GPU passthrough
make disk # Disk usage report
make backup # Backup Docker configs
make cleanup # Clean unused Docker resources
Stack Management
make deploy-portainer # Deploy Portainer
make deploy-ollama # Deploy Ollama
make logs-ollama # View Ollama logs
make update-jellyfin # Update Jellyfin to latest
make stop-nextcloud # Stop Nextcloud stack
See Stacks Reference for complete stack inventory and deployment procedures.
Development Setup
Python Environment
Some automation scripts require Python dependencies:
# Activate virtual environment
source .venv/bin/activate
# Install/update dependencies
pip install -r requirements.txt
# Deactivate when done
deactivate
Service Development
See individual service documentation:
Service Ports Reference
| Service | Port | Description |
|---|---|---|
| Portainer | 8080 | Container management UI |
| Nginx Proxy Manager | 8000 | Reverse proxy admin |
| Open WebUI | 8081 | LLM chat interface |
| Nextcloud | 8082 | Cloud storage |
| Core API | 8083 | Infrastructure management API |
| Organizr | 8084 | Unified dashboard |
| Headscale | 8085 | VPN control server |
| Jellyfin | 8096 | Media streaming |
| Uptime Kuma | 3001 | Service monitoring |
| Gitea | 3002 | Git repository hosting |
| Gitea SSH | 2222 | Git SSH access |
| PostgreSQL Shared | 5432 | Shared database (internal) |
| Redis Shared | 6379 | Shared cache (internal) |
| Qdrant | 6333, 6334 | Vector database |
| Ollama | 11434 | ML model API |
| Netdata | 19999 | System monitoring |
See Stacks Reference for complete port allocation.
GPU Services
Two services leverage the RTX 2080 Ti:
- Ollama - ML model inference (3B-13B parameter models)
- Jellyfin - Hardware video transcoding (NVENC)
See GPU Docker Configuration for setup.
Storage Strategy
SSD (Performance): /home/jpmschweitzer/docker-data/
- Docker configs, databases, cache, container images
HDD (Capacity): /mnt/media/
- Media files, user data, backups
See Stacks Reference for details.
Current Phase
Phase 2 of AI Orchestrator Enhancement (Memory Systems) 🔄 In Progress
See STATUS.md for detailed progress tracking.
Contributing
This is a personal infrastructure project. For AI agents:
- Read AGENTS.md first - Mandatory guidelines
- Follow conventional commit format
- Test GPU access before deploying GPU services
- Update STATUS.md when completing phases
Resources
Version: 0.7.1 Last Updated: 2025-11-20 System: tower-of-joy