Servizi e integrazioni
Questa sezione descrive i servizi esterni usati da Architecture Coffee e il confine che impedisce a ciascun provider di diventare autorità su dati, decisioni o operazioni che appartengono all'applicazione.
La pagina di un provider non è una guida di configurazione
Le pagine spiegano il contratto stabile del repository. Non contengono credenziali, identificatori privati, valori di console, evidenza mutabile di produzione o autorizzazioni operative.
Mappa dei servizi
- Cloudflare Workers: esecuzione API e asset statici.
- Cloudflare D1: autorità editoriale e operativa runtime.
- Cloudflare Access: autenticazione del confine Admin.
- GitHub App: capability e dispatch Frontend server-owned.
- GitHub Actions ed Environments: validazione ed esecuzione repository-owned.
- Mailjet: destinatari, consenso, Campaign Draft e delivery.
- Provider AI: generazione di candidate Issue Content JSON.
- Cloudflare Pages: hosting statico del portale live su
https://docs.architecturecoffee.it.
La vista trasversale è in confini e flussi. Le procedure di mutazione restano in Deployment e operazioni.
Contratto standard di ogni pagina
Ogni servizio risponde alle stesse dieci domande:
- a cosa serve;
- quali componenti lo usano;
- quali dati o artefatti scambia;
- come separa autenticazione e autorizzazione;
- cosa possiede il provider;
- cosa possiede Architecture Coffee;
- quali operazioni sono automatiche, manuali o protette;
- come fallisce e come l'applicazione resta fail-closed;
- quali verifiche operative sono disponibili;
- quali ADR, contratti e runbook restano canonici.
La validazione del portale rende obbligatori pagina e sezioni, così i confini non possono scomparire per una modifica accidentale della navigazione.
Regole comuni
- un provider esegue una capability, non concede autorità editoriale;
- autenticazione, autorizzazione, approvazione e dispatch sono fasi distinte;
- payload privati e dati destinatario non diventano documentazione o log;
- mock e dry-run non provano un'operazione live;
- timeout, risposta parziale o evidenza non univoca non sono successo;
- pubblicazione, Campaign Draft, scheduling e delivery restano operazioni separate.