Vai al contenuto

Topologia e responsabilità

Architecture Coffee distribuisce due componenti indipendenti per ambiente. Il Frontend Worker serve l'esportazione statica Next.js; l'API Worker esegue la logica applicativa e possiede i binding runtime.

flowchart TB
    subgraph utenti["Browser e operatori"]
        pubblico["Lettore pubblico"]
        admin["Operatore Admin"]
    end
    subgraph frontend["Frontend Worker statico"]
        sito["HTML, asset, sitemap, robots e 404"]
    end
    subgraph api["API Worker"]
        rotte["API pubbliche e Admin"]
        auth["Autorizzazione applicativa"]
        job["Code e provider"]
    end
    access["Cloudflare Access"]
    d1["D1"]
    github["GitHub Actions protette"]
    pubblico --> sito
    admin --> access
    access --> sito
    access --> rotte
    sito -->|"GET pubbliche e CORS Admin"| rotte
    rotte --> auth
    rotte --> d1
    rotte --> job
    github -->|"deployment separato"| sito
    github -->|"deployment separato"| api
    github -->|"migrazione separata"| d1

Ownership per ambiente

Superficie Sviluppo Produzione Responsabilità
Frontend pubblico e shell Admin development.architecturecoffee.it architecturecoffee.it Frontend Worker statico
API, diagnostica e Admin API api.development.architecturecoffee.it api.architecturecoffee.it API Worker
Persistenza runtime D1 sviluppo D1 produzione API Worker e migrazioni repository-owned
Autenticazione Admin Cloudflare Access sviluppo Cloudflare Access produzione Access autentica; l'API autorizza
Esecuzione remota GitHub Environment development GitHub Environment production workflow manuali e credenziali isolate

Il Frontend non ha main, D1, Queue, service binding, variabili applicative o segreti. Il suo pacchetto è quindi verificabile come asset-only e binding-free. L'API possiede D1, Queue, autenticazione, autorizzazione, provider e diagnostica.

Confini delle route

Il contratto di parità delle route stabilisce l'owner di ogni famiglia:

  • HTML canonico, asset, sitemap, robots e pagina 404 appartengono al Frontend;
  • JSON pubblico, testo Issue, feedback, diagnostica e Admin API appartengono all'API;
  • GET e HEAD /feedback sono verifiche in sola lettura, mentre POST è l'unica persistenza;
  • /admin/** richiede Access e il permesso applicativo previsto dalla route.

Un hostname posseduto da entrambi i Worker, un fallback HTML servito dall'API o un binding runtime nel Frontend sono difetti di topologia e condizioni di stop.

Perché la separazione esiste

  • Blast radius: un errore Frontend non richiede il rollback dell'API.
  • Segreti: gli asset pubblici non ricevono credenziali o binding privati.
  • Dati: una migrazione D1 non è nascosta dentro un deployment.
  • Routing: ogni dominio ha un owner unico e verificabile.
  • Recupero: ogni componente conserva un proprio target di rollback.

Proseguire con controlli ed evidenza.