foodlinkk-command-center/docs/PLATFORM-AZ.md

# Foodlinkk Command Center — Platform A tot Z

*Laatst bijgewerkt: juni 2026 · VM106 `10.4.7.18`*

---

## A. Architectuur

```
Proxmox 10.4.7.14 (Dell R340)
├── VM105 10.4.7.19 — Ollama, ChromaDB, Herman orchestrator :8090
└── VM106 10.4.7.18 — Command Center (Docker)
    ├── cockpit :8600
    ├── tools-api :8700
    ├── gitea :3001
    ├── email-agent :8801
    ├── browser-agent :7790
    ├── prometheus :9090
    ├── grafana :3002
    └── PostgreSQL foodlinkk_db (host)
```

**Dataflow:** Browser → Cockpit → (proxy) Tools API → PostgreSQL / externe APIs

---

## B. Bestandslocaties

| Pad | Inhoud |
|-----|--------|
| `/home/aissa/foodlinkk-command-center` | Volledige monorepo (live) |
| `/home/aissa/nas-clients` | Klant-NAS (gemount in cockpit) |
| `/tmp/sysops-daily.log` | SysOps cron log |
| `/tmp/herman-daily.log` | Herman briefing cron |

---

## C. Cockpit — alle pagina's

| Route | Module |
|-------|--------|
| `/` | Herman CEO dashboard |
| `/herman` | Herman chat (delegatie, packaging, foto's) |
| `/agents` | Souls, mesh, goedkeuringen, events |
| `/retail` | Retail 360 |
| `/marketing` | Social, reclame, RSS |
| `/clients` | CRM + supermarkten |
| `/products`, `/suppliers` | Assortiment & inkoop |
| `/projects` | Food-business projecten + NAS |
| `/packaging` | Packaging Studio |
| `/ops` | IT topology, SysOps verslag, Gitea |
| `/documents` | Documenten hub |
| `/settings` | Email, social, Herman permissions |
| `/studio` | ComfyUI |
| `/beurs` | Marktdata |

---

## D. Database (PostgreSQL)

Migraties in `migrations/`:

| # | Onderwerp |
|---|-----------|
| 001 | agent_events, clients |
| 005–008 | email, browser, pgvector |
| 011–017 | retail 360, CRM |
| 016 | packaging agent, sysops soul |
| 018 | agent_action_requests (goedkeuringen) |
| 019 | cockpit_projects, project_assets |
| 021 | locale_preferences (i18n) |
| 022 | NAS-structuur per klant |
| 023 | sysops_activity log |

**Kern-tabellen:** `agent_souls`, `agent_events`, `agent_action_requests`, `cockpit_projects`, `project_assets`, `packaging_outputs`, `config_backups`, `sysops_activity`, `clients`, `supermarkets`, `deals`

---

## E. Agents (16 + Herman)

| Key | Rol |
|-----|-----|
| herman | Co-CEO, briefing, orchestratie |
| sysops | IT, Gitea sync, maintenance |
| packaging | Verpakkingsontwerp |
| marketing | Social, campagnes |
| retail | Supermarkten 360 |
| research | Marktonderzoek |
| design | ComfyUI |
| … | bizdev, finance, sourcing, product, halal, knowledge, browser, hr, email |

**Events:** `agent_events` — zichtbaar op `/agents`, klikbaar per agent.

**Goedkeuringen:** SysOps vraagt vóór maintenance scan en optionele backup.

---

## F. SysOps — Gitea & verslag

### Automatische Gitea push

Bij **elke deploy** (`deploy-all.sh`):
1. Rsync code naar VM106
2. Docker rebuild
3. **SysOps pusht volledige repo** naar Gitea `main` (user `sysops`)

API: `POST /ops/gitea/sync` body `{"reason":"manual"}`

### Goedgekeurde backup

Na CEO ✓ op approval `config_backup` → zelfde volledige repo-sync.

### Activiteitenlog

Tabel `sysops_activity`:
- `gitea_sync` — deploy, backup
- `maintenance_scan` — na scan

Zichtbaar op **IT Ops** (`/ops`) → paneel "SysOps verslag".

### Herman briefing

`collect_briefing_data()` leest:
- `sysops_activity_24h`
- `sysops_events_24h`
- Sectie **"SysOps IT — laatste 24 uur"** in dagrapport

Cron: 07:00 SysOps requests, 07:30 Herman briefing.

---

## G. Gitea

- URL: http://10.4.7.18:3001
- Repo: `aissa/foodlinkk-command-center`
- SysOps user: `sysops` (write, setup via `scripts/setup_gitea_sysops.sh`)
- Documentatie staat **in de repo** onder `docs/`

**Clone op andere machine:**
```bash
git clone http://10.4.7.18:3001/aissa/foodlinkk-command-center.git
```

---

## H. Herman

- Chat: `/api/herman/chat`
- Briefing: `POST /api/herman/briefing`
- Orchestrator: `HERMAN_ORCHESTRATOR_URL` → VM105 `:8090`
- Packaging opdracht: `maak verpakking: pouch 100×140 voor Product X project #5`

---

## I. Packaging

- UI: `/packaging` — 6 types, brand, tekst, NAS-export
- API: Tools API `/packaging/*`
- NAS: `{klant}/projects/{id}/packaging/*.svg|png|pdf|json`
- Herman: `packaging_agent.py` → generate + events

---

## J. Projecten & NAS

Per klant: `/home/aissa/nas-clients/{slug}/`  
Per project: `projects/{id-naam}/photos|documents|packaging|exports|briefs/`

API: `/api/projects` — create met `ensure_nas: true`

---

## K. Deploy

```bash
# Vanaf dev machine met /tmp/foodlinkk-deploy of lokale clone:
bash deploy-all.sh
```

Stappen: rsync → migraties → docker build → health checks → Gitea sync → Herman briefing.

Omgevingsvariabelen: `.env.example` (niet committen).

---

## L. i18n

- `cockpit/static/i18n/nl.json`, `en.json`
- Selector in topbar
- Uitgebreid: nav, clients, products, suppliers

---

## M. Monitoring

- Prometheus `:9090`, Grafana `:3002`
- IT Ops topology: Proxmox + services live
- Infra snapshots: `infra_snapshots`

---

## N. Email

- Settings → SMTP accounts
- Tools API `POST /emails/send`
- Packaging kan designs emailen met downloadlinks

---

## O. Ontwikkeling

| Component | Tech |
|-----------|------|
| Cockpit | Python 3.11, FastAPI, Jinja2, Alpine.js |
| Tools API | FastAPI, psycopg2 |
| Viz | Chart.js, viz-engine.js |
| Packaging | svgwrite, python-barcode, Pillow, reportlab |

**Tests:** health curls in `deploy-all.sh` en `docs/DEPLOY.md`

---

## P. Veiligheid

- SysOps: geen destructieve acties zonder goedkeuring
- `.env` in `.gitignore`
- Gitea: geen public registration
- Wachtwoorden in docker-compose op server (niet in git idealiter — gebruik `.env`)

---

## Q. Troubleshooting

| Probleem | Actie |
|----------|-------|
| Cockpit 502 | `docker compose logs cockpit` |
| Gitea push faalt | `scripts/setup_gitea_sysops.sh`, check collaborator |
| Briefing leeg | `python3 scripts/herman_daily_digest.py` |
| NAS map ontbreekt | Project → ensure-nas of opnieuw aanmaken |

---

## R. Referenties

- [ARCHITECTURE.md](./ARCHITECTURE.md)
- [APPS.md](./APPS.md)
- [API.md](./API.md)
- [AGENTS.md](./AGENTS.md)
- [DEPLOY.md](./DEPLOY.md)
- [CONTEXT.md](./CONTEXT.md) — korte Cursor-context