# Diagram Viewer Wiki

Welcome to the **Diagram Viewer** project documentation.

This project provides a static web interface for viewing and managing network architecture diagrams generated with Python's `diagrams` library.

## 📚 Contents

- [Getting Started](#getting-started)
- [Development Guide](#development-guide)
- [Deployment Guide](#deployment-guide)
- [Architecture Overview](#architecture-overview)

---

## Getting Started

### Prerequisites

- Python 3.8+
- Graphviz
- Docker (for deployment)

### Quick Start

```bash
# Clone repository
git clone git@git.appmodel.nl:Tour/diagram.git
cd diagram

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Generate diagrams
python lan_architecture.py
python main.py
```

---

## Development Guide

### Project Structure

```
diagram/
├── Dockerfile              # Multi-stage build for production
├── docker-compose.yml      # Docker Compose configuration
├── requirements.txt        # Python dependencies
├── lan_architecture.py     # LAN architecture diagram generator
├── main.py                 # Main diagram generator
├── public/
│   └── index.html         # Live Mermaid diagram editor
└── wiki/                  # Documentation (this wiki)
```

### Adding New Diagrams

1. Create a new Python file (e.g., `network_diagram.py`)
2. Import required components from `diagrams` library
3. Define your architecture using context managers
4. Run the script to generate PNG output

Example:
```python
from diagrams import Diagram, Cluster
from diagrams.onprem.network import Router
from diagrams.generic.device import Mobile

with Diagram("My Network", show=False, filename="my_network"):
    router = Router("Gateway")
    device = Mobile("Phone")
    device >> router
```

### Testing Locally

```bash
# Generate diagrams
python lan_architecture.py

# View output
ls -la *.png

# Test with local web server
python -m http.server 8000 --directory public/
# Open: http://localhost:8000
```

### Available Icons

The `diagrams` library provides icons from multiple providers:
- **OnPrem**: Network, compute, storage, etc.
- **Cloud**: AWS, Azure, GCP services
- **Generic**: Network devices, blank nodes
- **Custom**: Use your own images

See: [Diagrams Documentation](https://diagrams.mingrammer.com/docs/nodes/overview)

---

## Deployment Guide

### Overview

The project uses a fully automated Docker-based deployment pipeline:

1. **Develop** on local machine
2. **Commit & Push** to Gitea
3. **Auto-Deploy** via post-receive hook
4. **Build** multi-stage Docker image
5. **Serve** via Traefik reverse proxy

### Deployment Steps

#### 1. Initial Setup

```bash
# On server: Create app structure
apps-create diagram static-fe

# This creates:
# - /opt/apps/diagram (git repository)
# - /home/tour/infra/diagram/docker-compose.yml
```

#### 2. Configure Gitea Hook

In repository **Settings → Git Hooks → post-receive**:

```bash
#!/usr/bin/env bash
/usr/local/bin/app-deploy diagram
```

#### 3. Deploy

Simply push to Gitea:

```bash
git push origin main
```

The server automatically:
- Pulls latest code
- Rebuilds Docker image
- Restarts container
- Updates live site at https://diagram.appmodel.nl

### Manual Deployment

If needed:

```bash
# On server
app-deploy diagram

# Or step-by-step
cd /opt/apps/diagram
git pull
cd /home/tour/infra/diagram
docker compose up -d --build diagram
```

### Monitoring

```bash
# View deployment logs
tail -f /var/log/app-deploy-diagram.log

# View container logs
cd /home/tour/infra/diagram
docker compose logs -f diagram

# Check container status
docker compose ps
```

---

## Architecture Overview

### Infrastructure

```
┌─────────────────────────────────────────────┐
│           Production Architecture           │
├─────────────────────────────────────────────┤
│                                             │
│  ┌──────────────┐                          │
│  │   Gitea      │  (Source of Truth)        │
│  │ Tour/diagram │                          │
│  └──────┬───────┘                          │
│         │ git push                          │
│         ↓                                   │
│  ┌──────────────┐                          │
│  │ Post-Receive │  (Auto-trigger)           │
│  │     Hook     │                          │
│  └──────┬───────┘                          │
│         │ app-deploy diagram                │
│         ↓                                   │
│  ┌──────────────────────┐                  │
│  │  /opt/apps/diagram/  │                  │
│  │   (Git Repository)   │                  │
│  └──────┬───────────────┘                  │
│         │ git pull                          │
│         ↓                                   │
│  ┌──────────────────────┐                  │
│  │ Docker Build Process │                  │
│  │ ┌─────────────────┐  │                  │
│  │ │ Stage 1: Build  │  │                  │
│  │ │ - Python        │  │                  │
│  │ │ - Graphviz      │  │                  │
│  │ │ - Generate PNGs │  │                  │
│  │ └─────────────────┘  │                  │
│  │ ┌─────────────────┐  │                  │
│  │ │ Stage 2: Serve  │  │                  │
│  │ │ - Nginx         │  │                  │
│  │ │ - Static files  │  │                  │
│  │ └─────────────────┘  │                  │
│  └──────┬───────────────┘                  │
│         │ container starts                  │
│         ↓                                   │
│  ┌──────────────────────┐                  │
│  │  diagram-viewer      │                  │
│  │   Container :80      │                  │
│  └──────┬───────────────┘                  │
│         │ traefik_net                       │
│         ↓                                   │
│  ┌──────────────────────┐                  │
│  │      Traefik         │                  │
│  │  Reverse Proxy       │                  │
│  │  + Let's Encrypt     │                  │
│  └──────┬───────────────┘                  │
│         │ HTTPS                             │
│         ↓                                   │
│  diagram.appmodel.nl                       │
│                                             │
└─────────────────────────────────────────────┘
```

### Network Topology

The diagram viewer documents our home lab infrastructure:

- **LAN 192.168.1.0/24**: Main network
  - Core server (192.168.1.159): Traefik, Gitea, Dokku, Auction stack, MI50/Ollama
  - DNS server (192.168.1.163): AdGuard, Artifactory, CI runner
  - Home Assistant (192.168.1.193)
  - Atlas worker (192.168.1.100)
  - IoT devices

- **Tether 192.168.137.0/24**: Isolated subnet
  - Hermes worker (192.168.137.239)
  - Plato worker (192.168.137.163)

### Services

| Service | URL | Description |
|---------|-----|-------------|
| Diagram Viewer | https://diagram.appmodel.nl | This application |
| Gitea | https://git.appmodel.nl | Git hosting |
| Auction Frontend | https://auction.appmodel.nl | Auction platform |
| Aupi API | https://aupi.appmodel.nl | Backend API |
| Dokku | https://dokku.lan | PaaS platform |

---

## Additional Resources

### Related Documentation

- [DEPLOY_SERVER_SETUP.md](../DEPLOY_SERVER_SETUP.md) - Detailed deployment guide
- [DEPLOYMENT_GUIDE.md](../DEPLOYMENT_GUIDE.md) - General deployment pipeline
- [README.md](../README.md) - Project overview

### External Links

- [Diagrams Library](https://diagrams.mingrammer.com/)
- [Graphviz](https://graphviz.org/)
- [Mermaid.js](https://mermaid.js.org/) (used in live editor)
- [Traefik Documentation](https://doc.traefik.io/traefik/)
- [Docker Compose](https://docs.docker.com/compose/)

### Contributing

To contribute to this project:

1. Create a feature branch
2. Make your changes
3. Test locally
4. Submit a pull request in Gitea
5. Wait for automatic deployment after merge

---

## Troubleshooting

### Common Issues

#### Diagrams Not Generating

**Problem**: Python script fails to generate PNG files

**Solution**:
```bash
# Check Graphviz installation
dot -V

# Reinstall if needed
# macOS: brew install graphviz
# Ubuntu: sudo apt-get install graphviz
# Windows: choco install graphviz

# Verify Python dependencies
pip list | grep diagrams
pip install --upgrade diagrams
```

#### Container Build Fails

**Problem**: Docker build fails during deployment

**Solution**:
```bash
# Check deployment logs
tail -f /var/log/app-deploy-diagram.log

# Rebuild manually with verbose output
cd /home/tour/infra/diagram
docker compose build --no-cache --progress=plain diagram
```

#### Site Not Accessible

**Problem**: Container runs but site not reachable

**Solution**:
1. Check DNS: `nslookup diagram.appmodel.nl`
2. Verify Traefik labels: `docker inspect diagram-viewer | grep traefik`
3. Check Traefik logs: `docker logs traefik`
4. Test container directly: `curl http://localhost:PORT`

#### Changes Not Reflected

**Problem**: Pushed changes but site unchanged

**Solution**:
```bash
# Force rebuild on server
cd /home/tour/infra/diagram
docker compose down
docker compose up -d --build --force-recreate diagram

# Clear browser cache
# Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (macOS)
```

---

## Contact & Support

For issues, questions, or suggestions:

1. Check this wiki
2. Review [DEPLOY_SERVER_SETUP.md](../DEPLOY_SERVER_SETUP.md)
3. Check container logs
4. Contact the infrastructure team

---

**Last Updated**: 2025-12-02
**Version**: 1.0.0
**Maintainer**: Tour