# ═══════════════════════════════════════════════════════════════════════════════
#                         JARVIS PRIMARY - MASTER README
#                           Main Control Server (Berlin)
# ═══════════════════════════════════════════════════════════════════════════════
# Last Updated: 2024-12-31
# Maintainer: JARVIS AI (für Daddy)
# ═══════════════════════════════════════════════════════════════════════════════

## 🖥️ SYSTEM OVERVIEW

| Property      | Value                                    |
|---------------|------------------------------------------|
| Hostname      | realJarvisAI                             |
| Role          | Primary Control Server                   |
| IP (Public)   | 185.114.28.11                            |
| IP (VPN)      | 10.80.0.235                              |
| IP (Docker)   | 172.17.0.1, 172.18.0.1, 172.19.0.1       |
| SSH User      | root                                     |
| Home          | /root                                    |
| Location      | Hetzner Berlin                           |
| Domain        | realjarvis.ai                            |

## 📁 DIRECTORY STRUCTURE

### /root/ (Home)
```
├── jarvis-chat/               # 🤖 MAIN JARVIS CHAT
│   ├── jarvis-chat.py         # Main Entry Point
│   ├── lib/                   # Python Modules
│   │   ├── brain_chat.py      # Brain/Memory
│   │   ├── brain_search.py    # Vector Search
│   │   ├── tools_loader.py    # Tool System
│   │   ├── ssh_tools.py       # SSH Functions
│   │   ├── llm_service.py     # LLM API
│   │   └── ...
│   ├── boot/                  # Boot Prompts/Context
│   ├── docs/                  # Documentation
│   ├── .venv-chat/            # Python Virtualenv
│   └── docker-compose.yml     # DB Stack
│
├── jarvis-code/               # 🔧 JARVIS CODE AGENT
│   ├── jarvis-code.py         # Code Agent
│   ├── lib/                   # Shared Modules
│   └── .venv-code/            # Python Virtualenv
│
├── jarvis-voice-client/       # 🎤 Voice Client (OLD)
├── jarvis-voice-client-v2/    # 🎤 Voice Client V2
│
├── jarvis-data/               # 📦 Data/Backups
├── jarvis-notes/              # 📝 Notes
├── jarvis-3d-logo/            # 🎨 3D Logo Assets
├── jarvis-mac-client/         # 💻 Mac Client
├── jarvis-matrix-fx/          # 🎬 Matrix Effects
│
├── deep_researches/           # 📚 Research Documents
│
├── JARVIS_DOCUMENTATION.md    # 📖 Main Docs
├── todo.md                    # ✅ Todo List
└── close-to-v0-5.txt          # 📋 Version Notes
```

### /data/ (Data Volume)
```
├── jarvis/                    # 🗄️ DOCKER VOLUMES
│   ├── postgres/              # PostgreSQL Data
│   ├── qdrant/                # Vector DB Data
│   ├── redis/                 # Redis Data
│   ├── backups/               # Backups
│   └── docker-compose.yml     # Compose File
│
├── jarvis-os/                 # 🖥️ JARVIS-OS ISO BUILDER
│   ├── src/                   # Source Code
│   ├── templates/             # ISO Templates
│   ├── debianiso/             # Build Output
│   ├── recipes/               # Build Recipes
│   ├── build/                 # Build Directory
│   ├── .venv/                 # Python Venv
│   └── install                # Install Script
│
├── gitresources/              # 📦 Git Resources/Mirrors
│
├── musa/                      # 🔬 MUSA Testing
│
└── tmp/                       # Temporary Files

# ISOs (in /data/)
├── n0brain_debian-13.2.0_amd64_noprompt_debian.iso
├── n0brain_debian-13.2.0_arm64_noprompt_debian.iso
└── n0brain_debian-13.2.0_arm64_noprompt_jarvis-os.iso
```

## 🐳 DOCKER INFRASTRUCTURE

### Running Containers
| Container            | Port        | Purpose                |
|----------------------|-------------|------------------------|
| jarvis-postgres      | 5433        | Main PostgreSQL        |
| jarvis-code-postgres | 5434        | Code Agent PostgreSQL  |
| jarvis-redis         | 6380        | Main Redis             |
| jarvis-redis-chat    | 6381        | Chat Redis             |
| jarvis-redis-code    | 6382        | Code Redis             |
| jarvis-qdrant        | 6335/6336   | Main Vector DB         |
| jarvis-qdrant-code   | 6337/6338   | Code Vector DB         |

### Docker Compose Location
```
/root/jarvis-chat/docker-compose.yml  # Main stack
/data/jarvis/docker-compose.yml       # Data volumes
```

## 🎤 VOICE API

### Service: jarvis-voice-api.service
- **Port:** 8765 (WebSocket)
- **Purpose:** Voice WebSocket API
- **Connects to:** RIG Whisper API

### Architecture
```
┌─────────────────────────────────────────────────────────────────────────┐
│                           VOICE PIPELINE                                │
│                                                                         │
│  MacBook ──HTTPS:443──▶ api.realjarvis.ai (RIG)                        │
│                              │                                          │
│                              ├── /inference ──▶ Whisper (RIG)          │
│                              │                                          │
│                              └── /voice ──▶ PRIMARY:8765 ◄─────────┐   │
│                                             (Voice API)             │   │
│                                                  │                  │   │
│                                                  ▼                  │   │
│                                             PostgreSQL              │   │
│                                             (Context)               │   │
│                                                  │                  │   │
│                                                  ▼                  │   │
│                                             LLM (RIG)               │   │
│                                             SGLang:30000            │   │
│                                                  │                  │   │
│                                                  ▼                  │   │
│                                             Response ───────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
```

## 🔧 SYSTEMD SERVICES

| Service                    | Description              | Status  |
|----------------------------|--------------------------|---------|
| jarvis-voice-api.service   | Voice WebSocket API      | active  |

## 🌐 NGINX CONFIGURATION

### File: /etc/nginx/sites-enabled/

| Config               | Domain                | Purpose           |
|----------------------|-----------------------|-------------------|
| api.realjarvis.ai    | api.realjarvis.ai     | Voice/API Proxy   |
| forgejo              | git.realjarvis.ai     | Git Server        |

## 🗄️ DATABASES

### PostgreSQL (jarvis) - Port 5433
| Table       | Purpose                          |
|-------------|----------------------------------|
| projects    | Project Management               |
| plans       | Project Plans                    |
| machines    | Infrastructure Inventory         |
| tools       | Tool Registry                    |
| chat_history| Chat Logs                        |
| memories    | Brain Memories                   |
| summaries   | Context Summaries                |

### PostgreSQL (jarvis_code) - Port 5434
| Table       | Purpose                          |
|-------------|----------------------------------|
| sessions    | Code Agent Sessions              |
| history     | Code Agent History               |

### Redis - Port 6380/6381/6382
- Session Cache
- Tool Results Cache
- Agent State

### Qdrant - Port 6335/6337
- Vector Embeddings
- Semantic Search

## 🔗 CONNECTIONS

### Incoming
- git.realjarvis.ai → Forgejo
- api.realjarvis.ai → Proxy to RIG

### Outgoing
- → RIG (10.0.0.133) - Whisper, SGLang
- → MacBook - Voice Responses

## 📝 COMMON TASKS

### Restart Voice API
```bash
sudo systemctl restart jarvis-voice-api
```

### Restart Docker Stack
```bash
cd /root/jarvis-chat && docker compose restart
```

### Check Logs
```bash
# Voice API
journalctl -u jarvis-voice-api -f

# Chat
tail -f /root/jarvis-chat/logs/chat.log

# Docker
docker logs jarvis-postgres
```

### Database Backup
```bash
cd /data/jarvis
docker exec jarvis-postgres pg_dump -U jarvis jarvis > backup.sql
```

### Connect to DB
```bash
docker exec -it jarvis-postgres psql -U jarvis jarvis
```

## 🆘 TROUBLESHOOTING

### Docker Container Down
```bash
cd /root/jarvis-chat
docker compose up -d
```

### Voice API Not Responding
```bash
sudo systemctl status jarvis-voice-api
sudo systemctl restart jarvis-voice-api
```

### Database Connection Issues
```bash
docker exec jarvis-postgres pg_isready -U jarvis
docker restart jarvis-postgres
```

### NGINX Issues
```bash
sudo nginx -t
sudo systemctl reload nginx
```

## 🔐 SECURITY

- SSH: Key-only authentication
- PostgreSQL: Docker network only
- Redis: Docker network only
- Qdrant: Docker network only
- NGINX: SSL/TLS (Let's Encrypt)

## 📊 RELATED MACHINES

| Machine    | IP            | Role      | Purpose              |
|------------|---------------|-----------|----------------------|
| RIG        | 10.0.0.133    | compute   | GPU Inference        |
| BACKUP     | 185.114.28.10 | backup    | Failover             |
| GIT        | 185.114.28.6  | git       | Forgejo Server       |
| MacBook    | (dynamic)     | client    | Development          |

# ═══════════════════════════════════════════════════════════════════════════════
# EOF - JARVIS PRIMARY README
# ═══════════════════════════════════════════════════════════════════════════════