Adriano
2f722f541c
- Docs/sistema-documentale/: master architettura multi-wiki - Docs/docugen-mcp/: design + implementation plan MCP server Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
886 lines
39 KiB
Markdown
886 lines
39 KiB
Markdown
# Sistema Documentale — Design Master
|
|
|
|
> Sistema documentale multi-wiki (personale, aziendale, scalabile a N) come
|
|
> vault Git di markdown, sincronizzato su Gitea (VPS), pubblicato in sola
|
|
> lettura via Quartz, accessibile da desktop (Obsidian + Claude Code),
|
|
> Android (Obsidian) e browser mobile, integrato con `mcp-docgen` per
|
|
> documenti formali e predisposto per pipeline di ingest futura
|
|
> (STT di riunioni, bot Telegram).
|
|
|
|
---
|
|
|
|
## Indice
|
|
|
|
1. [Panoramica e scopo](#1-panoramica-e-scopo)
|
|
2. [Componenti del sistema](#2-componenti-del-sistema)
|
|
3. [Struttura di un singolo wiki](#3-struttura-di-un-singolo-wiki)
|
|
4. [Configurazione multi-wiki](#4-configurazione-multi-wiki)
|
|
5. [Flusso Git end-to-end](#5-flusso-git-end-to-end)
|
|
6. [Integrazione con `mcp-docgen`](#6-integrazione-con-mcp-docgen)
|
|
7. [Pubblicazione web — Quartz multi-site](#7-pubblicazione-web--quartz-multi-site)
|
|
8. [Accesso da Android](#8-accesso-da-android)
|
|
9. [Storage degli asset binari](#9-storage-degli-asset-binari)
|
|
10. [Autenticazione e sicurezza](#10-autenticazione-e-sicurezza)
|
|
11. [Backup e disaster recovery](#11-backup-e-disaster-recovery)
|
|
12. [Setup iniziale — fasi implementative](#12-setup-iniziale--fasi-implementative)
|
|
13. [Estensioni future pianificate](#13-estensioni-future-pianificate)
|
|
14. [Decisioni e rationale](#14-decisioni-e-rationale)
|
|
|
|
---
|
|
|
|
## 1. Panoramica e scopo
|
|
|
|
### Cosa stiamo costruendo
|
|
|
|
Un sistema documentale che:
|
|
|
|
- **Archivia** documenti (relazioni, preventivi, note commercialista, idee, verbali riunione, ecc.) in più **wiki separati per dominio** (personale, aziendale, altri futuri) — tutti come file Markdown
|
|
- **Versiona** ogni wiki in un **repo Git separato** su Gitea self-hosted (VPS)
|
|
- **Pubblica** ogni wiki in sola lettura su **un sotto-dominio dedicato** (Quartz statico), con auth unificata
|
|
- **Integra** un generatore di documenti formali (`mcp-docgen`, già progettato) condiviso da tutti i wiki
|
|
- **Resta editabile** principalmente da desktop (Obsidian + Claude Code) e occasionalmente da Android (Obsidian mobile + Git plugin)
|
|
- **È predisposto** per estensioni future di ingest automatico: trascrizione riunioni via STT, bot Telegram per note vocali/testuali inviate da mobile
|
|
|
|
### Principi cardine
|
|
|
|
**Un wiki, un dominio, un repo, un ciclo di vita.** Wiki personale e wiki aziendale sono **fisicamente separati**: repo diversi, vault Obsidian diversi, siti Quartz diversi, asset separati, backup indipendenti. Una compromissione o un errore su uno non tocca l'altro. Un eventuale hand-off di un wiki (es. condivisione di `aziendale` con un collaboratore o commercialista) è possibile senza sforzo.
|
|
|
|
**Pattern riusabile.** Tutti i wiki seguono la stessa struttura interna (sezione 3), la stessa convenzione di frontmatter, lo stesso workflow Git. Aggiungere un terzo wiki (`wiki-<nome>`) è una replica meccanica.
|
|
|
|
**Infrastruttura condivisa.** Gitea, Quartz, nginx, Authelia, `mcp-docgen` sono servizi orizzontali usati da tutti i wiki. Una sola istanza di ciascuno.
|
|
|
|
**Flat-file + Git + Claude Code + Obsidian.** Niente database applicativo nel percorso di produzione del contenuto.
|
|
|
|
### Cosa NON fa
|
|
|
|
- Non è un DMS con workflow di approvazione / firma digitale integrata
|
|
- Non sostituisce il gestionale contabile
|
|
- Non fa OCR né ricerca semantica (eventualmente integrabili in futuro)
|
|
- Non supporta edit concorrente multi-utente (un operatore, Adriano)
|
|
- Non espone interfaccia di editing da browser (edit solo da Obsidian/Claude Code)
|
|
|
|
---
|
|
|
|
## 2. Componenti del sistema
|
|
|
|
### Mappa macro-componenti
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ DESKTOP (questa macchina, Linux Ubuntu) │
|
|
│ │
|
|
│ /home/adriano/Documenti/Git_XYZ/Documentale/ │
|
|
│ │
|
|
│ ├─ wiki-personale/ ← vault locale (clone git Gitea) │
|
|
│ ├─ wiki-aziendale/ ← vault locale (clone git Gitea) │
|
|
│ ├─ wiki-<altro>/ ← futuri wiki, stessa struttura │
|
|
│ │ │
|
|
│ ├─ wiki-personale-assets/ ← binari fuori git, rsync → VPS │
|
|
│ ├─ wiki-aziendale-assets/ ← idem │
|
|
│ │ │
|
|
│ └─ mcp-docgen/ ← sorgente MCP server (repo separato) │
|
|
│ │
|
|
│ Strumenti: │
|
|
│ • Obsidian: un vault per ogni wiki (switch-vault funzione nativa) │
|
|
│ • Claude Code: opera su cartelle del wiki selezionato │
|
|
│ • Obsidian Git plugin: auto-push per ciascun vault │
|
|
│ • systemd timer: rsync asset → VPS │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
│ ▲ │ ▲ │ ▲
|
|
│ git │ │ git │ │ rsync │
|
|
▼ │ ▼ │ ▼ │
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ VPS Hostinger │
|
|
│ │
|
|
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Gitea (un'istanza, più repo) │ │
|
|
│ │ • adriano/wiki-personale.git + post-receive hook │ │
|
|
│ │ • adriano/wiki-aziendale.git + post-receive hook │ │
|
|
│ │ ↓ (hook → quartz build per ciascun wiki) │ │
|
|
│ └───────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
|
│ │ Quartz build pipeline (una config per wiki) │ │
|
|
│ │ /opt/quartz-personale/ → build → /var/www/personale/ │ │
|
|
│ │ /opt/quartz-aziendale/ → build → /var/www/aziendale/ │ │
|
|
│ └───────────────────────────────────────────────────────────────────┘ │
|
|
│ │
|
|
│ ┌─────────────────────┐ ┌─────────────────────┐ │
|
|
│ │ /var/www/assets/ │ │ mcp-docgen (Docker) │ │
|
|
│ │ ├─ personale/ │ │ condiviso tra wiki │ │
|
|
│ │ └─ aziendale/ │ │ FastMCP HTTP │ │
|
|
│ └─────────────────────┘ │ OpenRouter LLM │ │
|
|
│ └─────────────────────┘ │
|
|
│ │
|
|
│ ┌───────────────────────────────────────────────────────────────────┐ │
|
|
│ │ nginx + Authelia (SSO unico) │ │
|
|
│ │ personale.<dominio> → /var/www/personale/ │ │
|
|
│ │ aziendale.<dominio> → /var/www/aziendale/ │ │
|
|
│ │ <w>.<dominio>/assets/ → /var/www/assets/<w>/ │ │
|
|
│ │ gitea.<dominio> → Gitea web UI │ │
|
|
│ │ docgen.<dominio> → mcp-docgen (solo API key, no SSO) │ │
|
|
│ └───────────────────────────────────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
▲
|
|
│ HTTPS + SSO (TOTP 2FA)
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ MOBILE Android │
|
|
│ • Obsidian app + Git plugin → un vault per ciascun wiki │
|
|
│ • Chrome/Firefox → consultazione siti sotto-dominio │
|
|
└─────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Ruoli sintetici
|
|
|
|
| Componente | Dove vive | Ruolo | Molteplicità | Stato |
|
|
|---|---|---|---|---|
|
|
| `wiki-<nome>/` | Desktop + Gitea VPS | Vault markdown versionato | **Per wiki** | Da creare |
|
|
| `wiki-<nome>-assets/` | Desktop + `/var/www/assets/<nome>/` | Binari | **Per wiki** | Da creare |
|
|
| `mcp-docgen` | VPS Docker | Generazione documenti formali | **Condiviso** | Design pronto |
|
|
| Gitea | VPS | Git remote | Unica istanza, più repo | Da installare |
|
|
| Quartz | VPS | SSG per wiki | **Un'istanza per wiki** (config + output separati) | Da configurare |
|
|
| nginx | VPS | Reverse proxy | Unico | Da configurare |
|
|
| Authelia | VPS | SSO 2FA | Unico | Da configurare |
|
|
|
|
---
|
|
|
|
## 3. Struttura di un singolo wiki
|
|
|
|
Tutti i wiki (personale, aziendale, futuri) seguono **identica struttura interna**. Schema isomorfico a `Cerbero_Brain` (raw immutabile + wiki LLM-managed), esteso con `documents/` per output prodotti e `areas/` come MOC tematiche.
|
|
|
|
```
|
|
wiki-<nome>/
|
|
├── CLAUDE.md # schema e regole del vault
|
|
├── README.md # intro human-readable
|
|
├── index.md # catalogo content-oriented
|
|
├── log.md # timeline append-only
|
|
│
|
|
├── raw/ # IMMUTABILE
|
|
│ ├── comunicazioni_in/ # mail ricevute, PEC, lettere
|
|
│ ├── documenti_ricevuti/ # markdown ricevuti, allegati testuali
|
|
│ ├── notes/ # appunti grezzi, voice-to-text (manual)
|
|
│ └── riunioni/ # trascrizioni riunioni grezze (STT futuro)
|
|
│
|
|
└── wiki/ # LLM-managed
|
|
├── documents/ # documenti prodotti da Adriano
|
|
│ ├── preventivi/ # (prevalente in wiki-aziendale)
|
|
│ ├── relazioni/
|
|
│ ├── verbali_riunione/ # note sintetiche strutturate da raw/riunioni/
|
|
│ └── comunicazioni_out/
|
|
│
|
|
├── entities/ # clienti, fornitori, persone, studi
|
|
│
|
|
├── concepts/ # procedure, template, framework
|
|
│
|
|
├── areas/ # MOC tematici
|
|
│
|
|
└── syntheses/ # analisi trasversali
|
|
```
|
|
|
|
### Contenuto tipico per wiki
|
|
|
|
| Wiki | Contenuto prevalente |
|
|
|---|---|
|
|
| **wiki-personale** | Idee, note personali, journal, documentazione privata (salute, famiglia, viaggi), inventari personali, consapevolezza finanziaria personale (distinta da Milito/Cerbero) |
|
|
| **wiki-aziendale** | Clienti, preventivi, relazioni, fatturazione, commercialista, fornitori, procedure aziendali, contratti, verbali riunione con clienti |
|
|
|
|
### Convenzioni comuni
|
|
|
|
Frontmatter, naming, wikilink, log.md append-only, index content-oriented: **identici** per tutti i wiki. Vedi esempi completi in §5 e §6.
|
|
|
|
Ogni wiki ha il **proprio `CLAUDE.md`** locale al suo root, che specifica:
|
|
- Identità del wiki (es. "wiki personale di Adriano")
|
|
- Dominio applicativo (cosa ci va, cosa non ci va)
|
|
- Eventuali regole peculiari (es. wiki-aziendale richiede che ogni `documents/preventivi/` menzioni un `entities/cliente`)
|
|
|
|
Claude Code, quando opera dentro un wiki, carica il suo `CLAUDE.md` contestuale (comportamento nativo).
|
|
|
|
---
|
|
|
|
## 4. Configurazione multi-wiki
|
|
|
|
### Registro dei wiki
|
|
|
|
File di riferimento: `/home/adriano/Documenti/Git_XYZ/Documentale/wikis.yaml`
|
|
|
|
```yaml
|
|
wikis:
|
|
- name: personale
|
|
local_path: wiki-personale
|
|
assets_path: wiki-personale-assets
|
|
remote: git@gitea.<dominio>:adriano/wiki-personale.git
|
|
publish_domain: personale.<dominio>
|
|
quartz_source: /opt/quartz-personale
|
|
quartz_output: /var/www/personale
|
|
vps_assets_path: /var/www/assets/personale
|
|
|
|
- name: aziendale
|
|
local_path: wiki-aziendale
|
|
assets_path: wiki-aziendale-assets
|
|
remote: git@gitea.<dominio>:adriano/wiki-aziendale.git
|
|
publish_domain: aziendale.<dominio>
|
|
quartz_source: /opt/quartz-aziendale
|
|
quartz_output: /var/www/aziendale
|
|
vps_assets_path: /var/www/assets/aziendale
|
|
```
|
|
|
|
Questo file è la **single source of truth** per scripting (sync, backup, provisioning nuovo wiki).
|
|
|
|
### Aggiungere un terzo wiki
|
|
|
|
Procedura meccanica:
|
|
|
|
1. Aggiungi voce a `wikis.yaml`
|
|
2. `gitea` web UI → crea repo privato `adriano/wiki-<nuovo>`
|
|
3. Script di provisioning (da scrivere in Fase 2): `./tools/new-wiki.sh <nome>` che:
|
|
- Crea struttura cartelle locale
|
|
- Inizializza git, primo commit, push
|
|
- Installa plugin Obsidian Git nel nuovo vault
|
|
- Crea config Quartz per il nuovo sotto-dominio
|
|
- Aggiunge virtual host nginx + cert Let's Encrypt
|
|
- Registra hook post-receive Gitea
|
|
|
|
### Scripting condiviso
|
|
|
|
Gli script operativi (backup, sync asset, provisioning) iterano su `wikis.yaml`, zero duplicazione.
|
|
|
|
---
|
|
|
|
## 5. Flusso Git end-to-end
|
|
|
|
### Remote e branch
|
|
|
|
- **Gitea self-hosted**: un server, più repo (uno per wiki)
|
|
- **Branch unico `main`** per repo (no PR, uso personale)
|
|
- **Commit strategy**: piccoli e frequenti, messaggi descrittivi (`doc(acme): preventivo v1`, `ingest: PEC 2026-04-15`, `refactor: split concepts/procedura-x`)
|
|
|
|
### Flusso desktop → Gitea (per ciascun wiki)
|
|
|
|
1. Edit markdown (Obsidian o Claude Code) nella cartella del wiki
|
|
2. **Obsidian Git plugin** in quel vault (configurato per-wiki):
|
|
- Auto-commit + push ogni 10 min
|
|
- Messaggio commit: `auto: {{date}}`
|
|
3. Gitea riceve push sul repo del wiki
|
|
4. Hook `post-receive` triggera **`quartz build` specifico di quel wiki** → `/var/www/<wiki>/`
|
|
5. nginx serve la nuova versione di `<wiki>.<dominio>`
|
|
|
|
### Flusso mobile Android → Gitea
|
|
|
|
Per ciascun vault (un vault per wiki) su Obsidian mobile:
|
|
|
|
1. Apri vault → pull manuale (bottone Git plugin)
|
|
2. Edita
|
|
3. Commit & Push manuale
|
|
|
|
### Fallback systemd timer (desktop)
|
|
|
|
Sotto `~/.config/systemd/user/`, un timer + service generici parametrizzati per-wiki:
|
|
|
|
```ini
|
|
# vault-sync@.service (template unit)
|
|
[Service]
|
|
Type=oneshot
|
|
WorkingDirectory=/home/adriano/Documenti/Git_XYZ/Documentale/%i
|
|
ExecStart=/usr/bin/git add -A
|
|
ExecStart=/bin/sh -c 'git diff --cached --quiet || git commit -m "auto: $(date -Iseconds)"'
|
|
ExecStart=/usr/bin/git pull --rebase --autostash
|
|
ExecStart=/usr/bin/git push
|
|
```
|
|
|
|
Abilita per wiki: `systemctl --user enable vault-sync@wiki-personale.timer`, `vault-sync@wiki-aziendale.timer`.
|
|
|
|
### Asset sync (per wiki)
|
|
|
|
Un timer rsync per wiki:
|
|
```bash
|
|
rsync -az --delete \
|
|
/home/adriano/Documenti/Git_XYZ/Documentale/wiki-<nome>-assets/ \
|
|
adriano@vps:/var/www/assets/<nome>/
|
|
```
|
|
|
|
Script unico che itera `wikis.yaml` e lancia rsync per ciascuno.
|
|
|
|
---
|
|
|
|
## 6. Integrazione con `mcp-docgen`
|
|
|
|
`mcp-docgen` è **condiviso** tra tutti i wiki. Il template selezionato determina il formato; la destinazione di archiviazione la scegli (o la suggerisce Claude Code) al momento della generazione.
|
|
|
|
### Tool MCP
|
|
|
|
| Tool | Uso |
|
|
|---|---|
|
|
| `template_create/update/delete/list/get` | Gestione template |
|
|
| `document_generate` | Genera markdown formale |
|
|
|
|
### Configurazione Claude Code
|
|
|
|
`~/.claude/.mcp.json`:
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"docgen": {
|
|
"type": "http",
|
|
"url": "https://docgen.<dominio>/mcp",
|
|
"headers": { "Authorization": "Bearer <API_KEY>" }
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Template iniziali (condivisi, taggati per wiki di provenienza tipica)
|
|
|
|
| Template | Wiki tipico | Uso |
|
|
|---|---|---|
|
|
| `preventivo-commerciale` | aziendale | Preventivi clienti |
|
|
| `relazione-audit` | aziendale | Relazioni tecniche |
|
|
| `lettera-formale` | aziendale o personale | Comunicazioni ufficiali |
|
|
| `nota-commercialista` | aziendale | Comunicazioni al commercialista |
|
|
| `verbale-riunione` | aziendale | Verbali post-riunione (anche da STT futuro) |
|
|
| `journal-entry` | personale | Entry diario personale strutturato |
|
|
|
|
I template hanno `tags: [wiki:aziendale]` o `[wiki:personale]` nel frontmatter per filtrarli in `template_list`, ma nulla impedisce di usarli cross-wiki se serve.
|
|
|
|
### Flusso "draft → formal → archivio in wiki corretto"
|
|
|
|
```
|
|
1. Adriano: "Prepara preventivo per Acme in wiki-aziendale"
|
|
|
|
2. Claude Code (contesto wiki-aziendale):
|
|
a) Legge wiki-aziendale/wiki/entities/Acme_SRL.md
|
|
b) Legge wiki-aziendale/wiki/concepts/Template_Preventivo.md
|
|
c) Prepara bozza grezza
|
|
d) Invoca mcp__docgen__document_generate:
|
|
template = "preventivo-commerciale"
|
|
content = bozza
|
|
variables = {cliente: "Acme SRL", piva: "...", ...}
|
|
e) Salva output in wiki-aziendale/wiki/documents/preventivi/YYYY-MM-DD_Acme_v1.md
|
|
f) Aggiorna wiki-aziendale/wiki/entities/Acme_SRL.md (storico preventivi)
|
|
g) Aggiorna wiki-aziendale/index.md e log.md
|
|
|
|
3. Adriano rivede in Obsidian (vault aziendale)
|
|
|
|
4. Finale → export PDF in wiki-aziendale-assets/clienti/Acme_SRL/
|
|
→ aggiorna status: sent
|
|
→ rsync asset → VPS
|
|
→ Git auto-push → Quartz rebuild → visibile su aziendale.<dominio>
|
|
```
|
|
|
|
### Quando NON usare `mcp-docgen`
|
|
|
|
- Note grezze, appunti, idee → markdown diretto
|
|
- Ingest di materiale ricevuto (va in `raw/` as-is)
|
|
- Template operativi interni (scritti manualmente in `concepts/`)
|
|
|
|
---
|
|
|
|
## 7. Pubblicazione web — Quartz multi-site
|
|
|
|
### Approccio
|
|
|
|
**Un'istanza Quartz per wiki.** Stessa versione del codice sorgente Quartz, configurazione separata, output separato, sotto-dominio separato.
|
|
|
|
### Layout VPS
|
|
|
|
```
|
|
/opt/quartz-personale/
|
|
├── quartz.config.ts # title: "Wiki Personale", baseUrl: "personale.<dominio>"
|
|
├── content/ # git checkout di wiki-personale (pull nel hook)
|
|
└── ...
|
|
|
|
/opt/quartz-aziendale/
|
|
├── quartz.config.ts # title: "Wiki Aziendale", baseUrl: "aziendale.<dominio>"
|
|
├── content/
|
|
└── ...
|
|
|
|
/var/www/personale/ # output Quartz personale
|
|
/var/www/aziendale/ # output Quartz aziendale
|
|
/var/www/assets/
|
|
├── personale/
|
|
└── aziendale/
|
|
```
|
|
|
|
### Hook `post-receive` (per repo)
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# hooks/post-receive di wiki-<nome>.git
|
|
set -e
|
|
WIKI_NAME=<nome>
|
|
WORKDIR=/opt/quartz-$WIKI_NAME
|
|
|
|
cd $WORKDIR/content
|
|
git pull --rebase
|
|
|
|
cd $WORKDIR
|
|
npx quartz build --output /var/www/$WIKI_NAME/
|
|
|
|
nginx -t && systemctl reload nginx
|
|
```
|
|
|
|
### nginx per wiki
|
|
|
|
Un virtual host per sotto-dominio:
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl http2;
|
|
server_name personale.<dominio>;
|
|
|
|
include /etc/nginx/authelia-location.conf;
|
|
|
|
location / {
|
|
include /etc/nginx/authelia-authrequest.conf;
|
|
root /var/www/personale;
|
|
try_files $uri $uri/ $uri.html =404;
|
|
}
|
|
|
|
location /assets/ {
|
|
include /etc/nginx/authelia-authrequest.conf;
|
|
alias /var/www/assets/personale/;
|
|
}
|
|
|
|
ssl_certificate /etc/letsencrypt/live/<dominio>/fullchain.pem;
|
|
ssl_certificate_key /etc/letsencrypt/live/<dominio>/privkey.pem;
|
|
}
|
|
# Stesso identico schema per aziendale.<dominio>, sostituendo "personale" con "aziendale"
|
|
```
|
|
|
|
### CSS print condiviso
|
|
|
|
Custom media-query `@media print` in un file `print.scss` copiato in entrambe le config Quartz, o mantenuto in un submodule Git condiviso.
|
|
|
|
---
|
|
|
|
## 8. Accesso da Android
|
|
|
|
Consultazione (90%) via browser sui sotto-domini. Edit occasionale via Obsidian mobile con **un vault separato per wiki**.
|
|
|
|
### Obsidian mobile multi-vault
|
|
|
|
Obsidian mobile supporta N vault. Ciascun vault è una cartella separata (che clona il repo Gitea del wiki corrispondente).
|
|
|
|
Setup per wiki:
|
|
1. Aggiungi vault in Obsidian Android (crea cartella locale, es. `/storage/emulated/0/Obsidian/wiki-personale/`)
|
|
2. Installa community plugin "Obsidian Git"
|
|
3. Clone via plugin: URL `https://gitea.<dominio>/adriano/wiki-personale.git` + **token personale Gitea** (scope: repo read/write)
|
|
4. Configurazione plugin:
|
|
- Auto-pull on load: on
|
|
- Auto-push: off
|
|
- Commit message: `mobile: {{date}}`
|
|
|
|
Ripeti per `wiki-aziendale`.
|
|
|
|
### Switch vault
|
|
|
|
Dalla home di Obsidian Android, icona a destra → lista vault → tap per switchare. Comodo e veloce.
|
|
|
|
### Limiti
|
|
|
|
- Android non supporta sync in background → azione manuale pull/commit/push
|
|
- Asset binari: via browser sotto-dominio, non Obsidian
|
|
- Evitare edit contemporaneo mobile vs desktop (pull sempre prima di editare)
|
|
|
|
---
|
|
|
|
## 9. Storage degli asset binari
|
|
|
|
### Struttura per wiki (identica)
|
|
|
|
```
|
|
wiki-<nome>-assets/
|
|
├── clienti/ # (prevalente in aziendale)
|
|
├── commercialista/ # (prevalente in aziendale)
|
|
├── personale/ # (prevalente in personale)
|
|
└── ...
|
|
```
|
|
|
|
### Sync
|
|
|
|
Systemd timer desktop, uno script, itera `wikis.yaml`:
|
|
```bash
|
|
for wiki in $(yq e '.wikis[].name' wikis.yaml); do
|
|
src="$HOME/Documenti/Git_XYZ/Documentale/wiki-$wiki-assets/"
|
|
dst="adriano@vps:/var/www/assets/$wiki/"
|
|
rsync -az --delete "$src" "$dst"
|
|
done
|
|
```
|
|
|
|
### Referenziazione dal markdown
|
|
|
|
Link assoluto al sotto-dominio del wiki:
|
|
```markdown
|
|
PDF firmato: [preventivo v1](https://aziendale.<dominio>/assets/clienti/Acme_SRL/2026-04-22_preventivo_v1_firmato.pdf)
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Autenticazione e sicurezza
|
|
|
|
### Authelia SSO condiviso
|
|
|
|
**Una sola istanza Authelia** protegge tutti i sotto-domini dei wiki e gli asset:
|
|
|
|
- `personale.<dominio>`, `aziendale.<dominio>`, `<nuovo>.<dominio>`
|
|
- Session cookie valido cross-subdomain (`Domain=<dominio>`)
|
|
- Utente unico `adriano` con TOTP 2FA (Aegis/Google Authenticator)
|
|
- Una login per aprire qualsiasi wiki
|
|
|
|
### Eccezioni
|
|
|
|
- `gitea.<dominio>` → login Gitea separato (con 2FA)
|
|
- `docgen.<dominio>` → solo API key header, non per browser umano
|
|
|
|
### ACL per wiki
|
|
|
|
Se in futuro vuoi dare accesso a `aziendale.<dominio>` a un collaboratore senza dare accesso a `personale.<dominio>`:
|
|
|
|
Authelia configurable ACL:
|
|
```yaml
|
|
access_control:
|
|
rules:
|
|
- domain: personale.<dominio>
|
|
policy: two_factor
|
|
subject: "user:adriano"
|
|
- domain: aziendale.<dominio>
|
|
policy: two_factor
|
|
subject: ["user:adriano", "user:collaboratore"]
|
|
```
|
|
|
|
Nessun lavoro extra nell'architettura — feature already-there.
|
|
|
|
### TLS
|
|
|
|
Let's Encrypt con cert SAN per tutti i sotto-domini, rinnovo automatico `certbot` + `systemd timer`.
|
|
|
|
---
|
|
|
|
## 11. Backup e disaster recovery
|
|
|
|
### Cosa salvare (per wiki)
|
|
|
|
| Asset | Criticità | Strategia |
|
|
|---|---|---|
|
|
| Repo Git Gitea (per wiki) | **Alta** | Clone desktop + Gitea VPS + snapshot settimanale |
|
|
| Asset binari (per wiki) | **Alta** (legale in aziendale) | Desktop + VPS + backup offsite weekly |
|
|
| `mcp-docgen` template + SQLite | Media | Snapshot volume Docker |
|
|
| Config VPS (nginx, Authelia, Quartz, Gitea) | Media | Repo `ops-vps` versionato |
|
|
|
|
### Strategia 3-2-1 (per wiki)
|
|
|
|
Ogni wiki ha la sua catena 3-2-1 indipendente. Script che itera `wikis.yaml` su VPS:
|
|
|
|
```bash
|
|
# systemd timer offsite-backup.timer, weekly
|
|
for wiki in $(yq e '.wikis[].name' /etc/documentale/wikis.yaml); do
|
|
rsync -az --delete \
|
|
/var/www/$wiki/ /var/www/assets/$wiki/ \
|
|
/var/opt/gitea/repositories/adriano/wiki-$wiki.git/ \
|
|
offsite:backups/documentale/$wiki/$(date +%Y-W%V)/
|
|
done
|
|
```
|
|
|
|
### Retention differenziabile per wiki
|
|
|
|
Potenzialmente (configurabile in `wikis.yaml`):
|
|
- `aziendale`: retention 10+ anni (documentazione legale)
|
|
- `personale`: retention 3 anni rotating (ok da revisione)
|
|
|
|
Implementabile con policy distinte per destinazione offsite (non critico al MVP).
|
|
|
|
### DR procedure
|
|
|
|
Documentata per ciascun wiki in `wiki-<nome>/wiki/concepts/DR_Procedure.md`. Procedura standard:
|
|
1. Repo perduto → clone da Gitea, riparti
|
|
2. Gitea VPS perduta → restore volume da offsite, repush da desktop
|
|
3. Tutto perduto → restore da offsite (perdita max 1 settimana)
|
|
|
|
---
|
|
|
|
## 12. Setup iniziale — fasi implementative
|
|
|
|
**Strategia:** porta **un solo wiki** fino in fondo (pipeline completa funzionante) prima di clonare la configurazione per il secondo. Così validi il modello end-to-end, poi replichi.
|
|
|
|
**Scelta del wiki pilota:** raccomando `wiki-aziendale` perché:
|
|
- Ha esigenze più concrete e immediate (preventivi, commercialista)
|
|
- Forza a testare `mcp-docgen` (template formali)
|
|
- Il pattern è più impegnativo, quindi se funziona lì il personale è banale
|
|
|
|
### Fase 1 — `wiki-aziendale` locale funzionante
|
|
|
|
**Deliverable:** vault locale usabile, Claude Code e Obsidian felici, commit git a repo locale.
|
|
|
|
1. Crea `Documentale/wikis.yaml` con solo `aziendale`
|
|
2. Crea struttura `wiki-aziendale/` (raw/ + wiki/{documents,entities,concepts,areas,syntheses})
|
|
3. Scrivi `wiki-aziendale/CLAUDE.md` (regole wiki aziendale)
|
|
4. `README.md`, `index.md`, `log.md` iniziali
|
|
5. `git init` + primo commit
|
|
6. Crea `wiki-aziendale-assets/`
|
|
7. Apri in Obsidian come vault, verifica rendering
|
|
8. Documento di prova (cliente fittizio + preventivo prova)
|
|
|
|
### Fase 2 — Gitea su VPS + sync wiki-aziendale
|
|
|
|
**Deliverable:** vault sincronizzato desktop ↔ Gitea.
|
|
|
|
1. Docker Gitea su VPS, `gitea.<dominio>` (TLS)
|
|
2. Crea repo `adriano/wiki-aziendale` (privato)
|
|
3. SSH key desktop → Gitea, token mobile Gitea
|
|
4. `git remote add` dal desktop, primo push
|
|
5. Plugin Obsidian Git → configura auto-push 10 min
|
|
6. Test round-trip
|
|
7. Systemd timer fallback
|
|
|
|
### Fase 3 — `mcp-docgen` su VPS + integrazione Claude Code
|
|
|
|
**Deliverable:** workflow "bozza → formale → archivio" in wiki-aziendale.
|
|
|
|
1. Implementa `mcp-docgen` (vedi suo design doc in `mcp-docgen/`)
|
|
2. Deploy Docker su `docgen.<dominio>`
|
|
3. Aggiungi a `~/.claude/.mcp.json`
|
|
4. Crea template: `preventivo-commerciale`, `relazione-audit`, `lettera-formale`, `nota-commercialista`, `verbale-riunione`
|
|
5. Test end-to-end dal wiki-aziendale
|
|
|
|
### Fase 4 — Quartz + nginx + TLS per wiki-aziendale
|
|
|
|
**Deliverable:** `aziendale.<dominio>` consultabile via HTTPS (senza auth stringente ancora, o basic auth temporanea).
|
|
|
|
1. Node su VPS, clone Quartz in `/opt/quartz-aziendale/`
|
|
2. Config Quartz (title, baseUrl)
|
|
3. CSS print
|
|
4. Hook `post-receive` in `wiki-aziendale.git` → `quartz build`
|
|
5. nginx virtual host + cert Let's Encrypt
|
|
6. Test da browser desktop + mobile
|
|
|
|
### Fase 5 — Authelia SSO + protezione
|
|
|
|
**Deliverable:** `aziendale.<dominio>` privato, login con TOTP.
|
|
|
|
1. Docker Authelia su VPS
|
|
2. Utente `adriano` con password + TOTP
|
|
3. nginx `auth_request` per dominio wiki e `/assets/`
|
|
4. Verifica login desktop + mobile
|
|
|
|
### Fase 6 — Asset sync + backup offsite (wiki-aziendale)
|
|
|
|
**Deliverable:** asset sync, backup 3-2-1 attivo.
|
|
|
|
1. Systemd timer rsync asset → VPS
|
|
2. nginx serve `/var/www/assets/aziendale/` (con auth)
|
|
3. Test link dai markdown
|
|
4. Backup offsite weekly (Hetzner Storagebox / B2)
|
|
|
|
### Fase 7 — Obsidian Android per wiki-aziendale
|
|
|
|
**Deliverable:** edit mobile funzionante.
|
|
|
|
1. Obsidian app + plugin Obsidian Git
|
|
2. Clone repo via plugin, token Gitea
|
|
3. Test edit mobile → push → verifica desktop
|
|
|
|
### Fase 8 — Replica per `wiki-personale`
|
|
|
|
**Deliverable:** secondo wiki operativo end-to-end.
|
|
|
|
Usando script `tools/new-wiki.sh` (scritto in Fase 2 o qui):
|
|
1. Aggiungi `personale` a `wikis.yaml`
|
|
2. Crea struttura locale
|
|
3. Crea repo Gitea
|
|
4. Provisioning Quartz + nginx + cert (wildcard o nuova SAN)
|
|
5. Clone vault Obsidian desktop + mobile
|
|
6. Testa ciclo completo
|
|
|
|
Replica banale — se Fasi 1-7 hanno validato il modello.
|
|
|
|
---
|
|
|
|
## 13. Estensioni future pianificate
|
|
|
|
Funzionalità **non** implementate in Fasi 1-8 ma già predisposte nell'architettura. Vengono sviluppate in fasi successive con i propri design + implementation doc.
|
|
|
|
### 13.1 Pipeline STT — trascrizione riunioni
|
|
|
|
**Scenario:** hai una riunione con cliente Acme, registri audio (Zoom, dittafono, registratore telefono). Vuoi che l'audio diventi automaticamente una bozza di verbale nel `wiki-aziendale`, pronta per revisione.
|
|
|
|
**Architettura prevista:**
|
|
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐
|
|
│ Registrazione │ │ Upload a VPS │ │ STT service VPS │
|
|
│ (mobile, │─────▶│ (curl / web │─────▶│ (Whisper.cpp │
|
|
│ registratore, │ │ form / SFTP) │ │ faster-whisper │
|
|
│ Zoom export) │ │ │ │ Docker) │
|
|
└─────────────────┘ └─────────────────┘ └────────┬─────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────┐
|
|
│ Inbox Service (nuovo microservizio VPS)│
|
|
│ │
|
|
│ ├─ Riceve trascrizione grezza │
|
|
│ ├─ Normalizza a markdown + frontmatter │
|
|
│ │ (source: stt, target_wiki: ?) │
|
|
│ ├─ Salva in /var/lib/inbox/drafts/ │
|
|
│ └─ Espone API: │
|
|
│ GET /drafts │
|
|
│ GET /drafts/{id} │
|
|
│ DELETE /drafts/{id} (consume) │
|
|
└────────────────┬────────────────────────┘
|
|
│
|
|
▼
|
|
┌────────────────────────────────────────┐
|
|
│ Claude Code desktop │
|
|
│ (comando /ingest-inbox o cron locale) │
|
|
│ │
|
|
│ ├─ GET /drafts │
|
|
│ ├─ Per ciascun draft: │
|
|
│ │ • Identifica target wiki │
|
|
│ │ (euristica + conferma Adriano) │
|
|
│ │ • Eventuale mcp-docgen format │
|
|
│ │ con template verbale-riunione │
|
|
│ │ • Commit in wiki/ │
|
|
│ │ documents/verbali_riunione/ │
|
|
│ │ • DELETE /drafts/{id} │
|
|
│ └─ Push git │
|
|
└────────────────────────────────────────┘
|
|
```
|
|
|
|
**Componenti nuovi da creare:**
|
|
|
|
- **`stt-service`**: container Docker con `faster-whisper` o `whisper.cpp`, API FastAPI minimale (`POST /transcribe` con audio → text). Modello `large-v3` per italiano.
|
|
- **`inbox-service`**: microservizio FastAPI che:
|
|
- Riceve audio (multipart) o testo
|
|
- Orchestra STT se audio
|
|
- Salva draft markdown in `/var/lib/inbox/drafts/<uuid>.md`
|
|
- Espone API REST protetta da API key
|
|
- **Claude Code skill `/ingest-inbox`**: comando che pollicia l'inbox, ingeriste nel wiki corretto con conferma utente
|
|
|
|
**Predisposizione nell'architettura corrente:**
|
|
|
|
- La cartella `raw/riunioni/` è **già prevista** nella struttura wiki (§3)
|
|
- Il template `verbale-riunione` è **già previsto** tra i template iniziali `mcp-docgen` (§6)
|
|
- nginx può ospitare `inbox.<dominio>` a un sottodomino aggiuntivo (Authelia o API key)
|
|
- Nessuna ristrutturazione necessaria quando arriva — è un'aggiunta pulita
|
|
|
|
**Fase stimata:** Fase 9 dopo completamento di Fase 8 e uso reale per qualche settimana.
|
|
|
|
### 13.2 Bot Telegram — ingest da mobile
|
|
|
|
**Scenario:** sei in giro, hai un'idea o vuoi registrare una nota vocale. Mandi messaggio (audio o testo) al tuo bot Telegram → finisce nel wiki corretto.
|
|
|
|
**Architettura prevista:**
|
|
|
|
```
|
|
┌─────────────┐ ┌─────────────────┐ ┌───────────────┐
|
|
│ Telegram │────────▶│ Bot Telegram │──────▶│ Inbox Service │
|
|
│ (tu, mobile│ message │ (python-tele- │ POST │ (stessa API │
|
|
│ vocale o │ │ gram-bot su │ │ di §13.1) │
|
|
│ testo) │ │ VPS Docker) │ └───────────────┘
|
|
└─────────────┘ └─────────────────┘ │
|
|
▼
|
|
(stessa pipeline
|
|
STT se audio,
|
|
poi drafts/,
|
|
poi Claude Code
|
|
desktop ingerisce)
|
|
```
|
|
|
|
**Logica minima del bot:**
|
|
|
|
- Riceve messaggio da chat autorizzata (whitelist per telegram ID)
|
|
- Se audio → forward a `stt-service`, poi `inbox-service`
|
|
- Se testo → forward diretto a `inbox-service` come markdown con `source: telegram`
|
|
- Risponde a Adriano: "Draft creato: ID xxx, target wiki non specificato"
|
|
- Opzionale: comandi slash tipo `/wiki aziendale` prima del messaggio per hint di targeting
|
|
|
|
**Predisposizione nell'architettura corrente:**
|
|
|
|
- È già disponibile il server MCP `cerbero-telegram` (vedi `~/.claude/.mcp.json` nel progetto Cerbero). Può essere riutilizzato o duplicato per questo uso, o si scrive un bot dedicato
|
|
- `inbox-service` previsto in §13.1 è la colonna portante di entrambe le integrazioni
|
|
- Nessuna ristrutturazione necessaria
|
|
|
|
**Fase stimata:** Fase 10 dopo §13.1.
|
|
|
|
### 13.3 Principio comune
|
|
|
|
Entrambe le estensioni seguono il pattern **"sorgente esterna → inbox VPS → Claude Code desktop ingerisce"**. Questo mantiene:
|
|
|
|
- **Single point of ingest** — `inbox-service` è l'unico che parla col VPS per contenuti nuovi
|
|
- **Claude Code resta autorevole** — decide target wiki, applica format, scrive il commit, mantiene coerenza
|
|
- **Evita commit diretti al wiki da VPS** — la VPS non ha mai bisogno di scrivere nei repo (solo leggerli per Quartz build e Gitea)
|
|
|
|
### 13.4 Altre estensioni meno urgenti
|
|
|
|
Tracciato qui per non dimenticarle:
|
|
|
|
- **OCR automatico** di scansioni ricevute (Tesseract + preprocessing, spinge output in inbox)
|
|
- **Ricerca semantica** del vault (integrazione con `claude-mem` o sistema embedding dedicato)
|
|
- **Auto-export PDF** per ogni `wiki/documents/` con status `final` (tramite pandoc + template LaTeX/typst)
|
|
- **Firma digitale** integrata in workflow preventivi (via CADES o firma semplice qualificata)
|
|
- **Collaboratore** su `wiki-aziendale` (già supportato da ACL Authelia §10)
|
|
|
|
---
|
|
|
|
## 14. Decisioni e rationale
|
|
|
|
### Perché separazione forte (repo per wiki)
|
|
|
|
- Separazione netta di ciclo di vita, backup, retention, ACL
|
|
- Possibilità di hand-off di un wiki senza esporre l'altro
|
|
- Un wiki rotto / corrotto non tocca gli altri
|
|
- Tradeoff accettato: niente wikilink cross-wiki — si duplica volentieri quando un soggetto è davvero rilevante per entrambi
|
|
|
|
### Perché Quartz e non SilverBullet/Wiki.js
|
|
|
|
- Nessun runtime app su VPS per il publish → zero superficie d'attacco extra
|
|
- Wikilink Obsidian nativi + backlinks + graph
|
|
- Velocità: pagine statiche
|
|
- Tradeoff: no edit da browser — accettato perché edit è da Obsidian/Claude Code
|
|
|
|
### Perché asset fuori git
|
|
|
|
- Git si gonfia con binari senza delta utili
|
|
- rsync separato → repo leggero per sempre
|
|
|
|
### Perché Authelia SSO unificato
|
|
|
|
- Una login per tutti i sotto-domini (cookie cross-subdomain)
|
|
- 2FA nativo
|
|
- ACL configurabili future (multi-utente parziale)
|
|
|
|
### Perché portare un wiki fino in fondo prima di replicare
|
|
|
|
- Valida l'intero stack end-to-end (meno rischio)
|
|
- Script di provisioning (`new-wiki.sh`) nasce dall'esperienza del primo setup
|
|
- Replica in Fase 8 è meccanica
|
|
|
|
### Perché `inbox-service` come hub per STT e Telegram
|
|
|
|
- Un solo endpoint normalizza l'ingest (API, storage, retention)
|
|
- Ogni sorgente futura (email-to-wiki, web-clipper, ecc.) riutilizza lo stesso hub
|
|
- Claude Code desktop resta il solo autorizzato a scrivere nei repo wiki
|
|
|
|
### Cose lasciate fuori scope (consapevolmente, MVP)
|
|
|
|
- OCR automatico
|
|
- Ricerca semantica / embeddings
|
|
- Auto-export PDF
|
|
- Firma digitale integrata
|
|
- Workflow di approvazione multi-step
|
|
- Multi-utente pieno
|
|
|
|
---
|
|
|
|
## Note finali
|
|
|
|
Design **incrementale** e **decomponibile**:
|
|
|
|
- Fase 1 sola → vault locale usabile (valore immediato)
|
|
- Fasi 1-4 → vault sincronizzato + pubblicato
|
|
- Fasi 1-7 → wiki-aziendale completo end-to-end
|
|
- Fase 8 → secondo wiki operativo
|
|
- Fase 9-10 → STT + Telegram (estensioni future)
|
|
|
|
Ogni fase è stop accettabile. Ogni fase avrà il proprio implementation plan prodotto da **writing-plans** quando ci arriveremo.
|
|
|
|
Cuore concettuale invariato: flat markdown + git + Claude Code + Obsidian + Quartz. Multi-wiki è replica di questo cuore, isolata per dominio. Estensioni future (STT, Telegram) sono aggiunte senza riarchitettura.
|