docs/SERVICE_ARCHITECTURE.md

NeuralAI Service Architecture

Podman Quadlet → Zo Service Mapping

Podman Concept	Zo Equivalent	NeuralAI Implementation
.container files	register_user_service()	3 registered services
systemd Requires=	Service startup order	model→webui dependency
systemd After=	Service health checks	tools→webui dependency
NFS volumes	/home/workspace/NeuralAI/	Built-in persistent storage
Restart=always	Zo supervisor	Auto-restart on crash
.network files	localhost networking	Services talk via HTTP

Service Definitions (like Quadlets)

neuralai-model.service (port 7001)

# Equivalent to: neuralai-model.container
[Service]
Entrypoint=python3 /home/workspace/Projects/NeuralAI/services/model_service.py
Port=7001
Restart=always
Environment=MODEL_PATH=/home/workspace/Projects/NeuralAI/checkpoints/v2_model

[Unit]
Description=NeuralAI Model Inference Service
# Model must be ready before webui
Before=neuralai-webui.service

neuralai-tools.service (port 7002)

# Equivalent to: neuralai-tools.container
[Service]
Entrypoint=python3 /home/workspace/Projects/NeuralAI/services/tools_service.py
Port=7002
Restart=always
Volume=/home/workspace/NeuralAI:/data:rw

[Unit]
Description=NeuralAI Tools Service (sandbox, storage)
# Tools must be ready before webui
Before=neuralai-webui.service

neuralai-webui.service (port 5000)

# Equivalent to: neuralai-webui.container
[Service]
Entrypoint=python3 /home/workspace/Projects/NeuralAI/services/webui_service.py
Port=5000
Public=true
Restart=always

[Unit]
Description=NeuralAI Web Interface
Requires=neuralai-model.service
Requires=neuralai-tools.service
After=neuralai-model.service
After=neuralai-tools.service

Dependency Graph

                    ┌─────────────────┐
                    │  neuralai-model │ :7001
                    │  (inference)    │
                    └────────┬────────┘
                             │
                             │ Requires
                             ▼
┌─────────────────┐    ┌─────────────────┐
│  neuralai-tools │───▶│  neuralai-webui │ :5000 (public)
│  (sandbox)      │    │  (router)       │
└─────────────────┘    └─────────────────┘
       :7002                   │
                                │
                       Public URL:
                       https://neuralai-webui-deandrewharris.zocomputer.io

Storage (like NFS volume)

/home/workspace/NeuralAI/
├── images/          # Generated images (shared)
├── documents/       # User documents for RAG (shared)
├── conversations/   # Chat history (shared)
├── models/          # Model checkpoints (shared)
└── cache/           # Temporary files (shared)

All services mount /home/workspace/NeuralAI/ - like an NFS volume shared across containers.

Management Commands

Like systemctl for Podman:

# Check status
systemctl --user status neuralai-*.service
# In Zo:
service_doctor("neuralai-model")

# Restart a service
systemctl --user restart neuralai-model.service
# In Zo:
update_user_service(service_id)

# View logs
journalctl --user -u neuralai-model.service
# In Zo:
cat /dev/shm/neuralai-model.log

Start/Stop All:

# Podman quadlet style
./services/start_all.sh    # Starts in dependency order
./services/stop_all.sh     # Stops in reverse order
./services/status.sh       # Shows all service states

Restart Behavior

Failure Scenario	What Happens
Model OOM crash	Only model service restarts, webui stays up
Tools timeout	Only tools service restarts
WebUI crash	Only webui restarts, model stays loaded
Model unhealthy	Webui returns 503, auto-recovery in progress

Benefits (Same as Your Podman Setup)

1. Isolation: Each service in its own process
2. Independence: Failures don't cascade
3. Dependencies: Proper startup ordering
4. Shared storage: All services access same /NeuralAI/
5. Declarative: Service configs are simple Python files
6. Auto-restart: Supervisor handles recovery
7. Observability: Separate logs per service

Current Status

✅ neuralai-model  (7001) - Ready, model loaded
✅ neuralai-tools  (7002) - Ready, sandbox active
✅ neuralai-webui  (5000) - Ready, public URL live

Public: https://neuralai-webui-deandrewharris.zocomputer.io