01 - Architettura

Guida iniziale · Stato

I nomi che non vanno confusi

Nome	Significato
Moonitoring Platform	L'ecosistema intero: sistemi, interfacce e regole comuni. Non è una singola repository o un progetto Google Cloud.
Area dei sistemi comuni / Platform	Raggruppamento tecnico usato per spiegare Access, distribuzione client e altri servizi trasversali. Ogni sistema conserva responsabilità, dati e API proprie.
moonitoring-platform-stage	Progetto Google Cloud concreto che ospita alcuni runtime comuni. Il nome non gli assegna tutte le risorse della piattaforma: rete, DB e CI sono in progetti dedicati.
Repository applicativa	Sorgenti di un sistema o di un'interfaccia. Può produrre più componenti, come backend e migratore. Non coincide automaticamente con un progetto cloud.
Modulo Terraform	Codice riusabile che configura un gruppo di risorse. Un progetto può usare diversi moduli; lo stesso modulo serve più sistemi.

Quindi aggiungere un servizio ad Access o Farm non richiede automaticamente un nuovo progetto, database o modulo Terraform. La scelta segue isolamento, risorse e responsabilità; la registrazione esplicita conserva il confine fra sistemi.

Dove sono le risorse

La parte predisposta è sotto l'organizzazione aziendale moonitoring.com. Le cartelle raggruppano ambienti e responsabilità; i progetti delimitano risorse, IAM e attribuzione dei costi. Uno stesso account di fatturazione può finanziare più progetti.

moonitoring.com
├─ 10-shared
│  ├─ moonitoring-infra-seed       state Terraform e identità delle fondamenta
│  └─ moonitoring-cicd             sorgenti GitHub, Build, Deploy e artefatti CI
└─ 30-stage
   ├─ moonitoring-net-stage       rete condivisa e collegamento privato SQL
   ├─ moonitoring-db-stage        una istanza PostgreSQL: sql-stage
   ├─ moonitoring-platform-stage  runtime dei sistemi comuni
   └─ moonitoring-farm-stage      runtime e risorse del prodotto Farm

È uno schema logico semplificato: omette cartelle intermedie e altri progetti aziendali. Conserviamo gli ID esistenti. Sviluppo locale con Docker; la produzione non viene attivata da questo piano.

sql-stage contiene i database access, releases, news, ai_gateway, farm e moochat; platform storico è conservato. I database separano dati e privilegi, ma condividono la capacità della stessa istanza.

Il progetto moonitoring-platform-stage ospita Access e ospiterà gli altri sistemi comuni. moonitoring-farm-stage ha anche bucket raw/dataset e code predisposte. Access e il backend+migratore Farm hanno una delivery collaudata; Farm ha provato anche il percorso privato fra progetti. Database e identità degli altri sistemi non ne provano l'esecuzione. Nei collaudi, Platform→Farm abbrevia soltanto questi due progetti Google Cloud.

Il secondo sistema collaudato è Farm, con backend e migratore reali. Build, DNS privato, migrazione, backend, separazione SQL e S2S sono verificati; metriche e una traccia applicativa sono ricevute. La riesecuzione del migratore ha confermato il no-op. Stato Farm.

Che cosa gestisce Terraform

Terraform descrive progetti, rete, database, archivi, code, identità, IAM e registrazioni delle pipeline. plan mostra le modifiche previste; apply le esegue. Bootstrap e stage hanno state remoti separati nel bucket delle fondamenta: lo state associa la configurazione alle risorse reali ed è protetto da accessi limitati e locking, che impedisce scritture concorrenti sullo stesso state. Non è l'archivio dei dati applicativi né il kit da dare a ogni sviluppatore.

Le release usano tre output selezionati: delivery, runtime e operator. Descrivono destinazioni e limiti della procedura. Vengono esportati e versionati, senza condividere l'intero state.

Che cosa gestisce il servizio

Una repository può contenere backend, migratore e altri componenti. Ogni componente attivato deve avere identità, risorse e modalità di rilascio esplicite. Un Service Cloud Run riceve richieste; un Job esegue un lavoro finito. Un worker può essere uno dei due secondo il suo funzionamento, non è necessariamente una macchina sempre accesa.

Il sistema è responsabile del proprio modello dati. Schema e migrazioni sono versionati nel repository applicativo, ma vengono applicati dal Job migratore con un'identità distinta. Backend e worker leggono o aggiornano i dati autorizzati, senza privilegi per modificare la struttura e senza eseguire migrazioni all'avvio. La separazione riguarda esecuzione e permessi: non richiede una repository distinta o modifiche manuali al database. Schema e rilasci SQL.

Il manifest descrive come eseguire il container: immagine, identità, rete, variabili e limiti. Cloud Deploy gestisce le revisioni applicative; Terraform prepara risorse e permessi. I due strumenti non devono modificare contemporaneamente la stessa specifica del workload.

Common e Design sono dipendenze di codice. Console è l'interfaccia interna dello staff, senza database proprio: usa le API dei sistemi. Access gestisce identità e autorizzazioni applicative; i servizi si chiamano direttamente con identità e policy previste, senza passare tutti attraverso Console o Access.

Per il percorso GitHub → cloud vedere 02; per le diverse autorizzazioni 04. Riferimenti verificati in 07.