Skip to main content

​
Architettura per contributori

Questa pagina è la vista architetturale orientata ai contributori. Le pagine di architettura del prodotto approfondiscono la logica di business; questa pagina risponde alla domanda più semplice: Dove dovrebbe intervenire un contributore per apportare una modifica?

​
App attive

  • apps/app: UI per l’operatore per inbox, contatti, template, campagne, journey, impostazioni e vista sul runtime.
  • apps/web: sito pubblico e pagine adiacenti al marketing.
  • apps/api: superficie API Next.js per endpoint interni, route di compatibilità e l’attuale ingress hosted alpha su Vercel.
  • apps/control-plane: runtime Node dedicato al lavoro di control-plane orientato a webhook e code. Rimane nel repository, ma non fa parte dell’attuale contratto hosted alpha.
  • apps/worker: ciclo di worker in background per l’elaborazione dell’outbox e la riconciliazione, pensato per Railway in alpha.
  • apps/storybook: workbench condiviso per i componenti.

​
Package condivisi

  • packages/auth: helper di autenticazione Supabase e gestione delle sessioni
  • packages/database: l’unico confine del data-plane supportato, inclusi contratti dei repository, adapter e proprietà orientata alle migration
  • packages/design-system: primitive UI condivise
  • packages/domain: contratti di dominio, dati mock e parsing dell’env a runtime
  • packages/feature-flags: helper per i flag e utility della toolbar
  • packages/observability: logging e strumentazione leggera del runtime
  • packages/security: helper di middleware per proxy/sicurezza
  • packages/whatsapp: schemi del provider, validazione dei payload e costanti di vincolo

​
Confine dell’area di lavoro attiva

La release line 0.1.x supporta intenzionalmente le aree di lavoro attive elencate sopra. Il repo mantiene anche diverse app e package derivati da next-forge fuori dall’insieme dell’area di lavoro attiva. Quei file sono materiale di scaffold per una futura attivazione di funzionalità, e non fanno ancora parte del contratto di verifica predefinito.

​
Suddivisione del runtime

I contributori dovrebbero pensare al repo come a tre livelli di esecuzione:
  1. Livello frontend in apps/app, apps/web e apps/docs
  2. Livello richiesta/HTTP in apps/api e apps/control-plane
  3. Livello di elaborazione in background in apps/worker
Supabase è il data plane comune a questi livelli.

​
Dove inserire le modifiche comuni

  • Aggiungi tipi condivisi o contratti di dominio in packages/domain.
  • Aggiungi la validazione del provider o gli schemi di payload in packages/whatsapp.
  • Aggiungi logica di accesso ai dati condivisa in packages/database.
  • Aggiungi UI riutilizzabile lato operatore in packages/design-system, con le storie Storybook.
  • Aggiungi comportamento specifico della route nell’app che effettivamente possiede quel runtime.

​
Nota sull’implementazione attuale

  • Il repo dispone già di una baseline dello schema Supabase e di un contratto auth/env.
  • Molte superfici di prodotto visibili ai contributori funzionano ancora tramite il livello di repository tipizzato basato su mock.
  • Il repo non dispone ancora di una vera abstrazione ORM; non descriverlo in questi termini finché gli adapter mock e Supabase non si conformano a interfacce di repository condivise.
  • Quando cambi un comportamento, documenta se la modifica riguarda il percorso mock, il percorso Supabase, o entrambi.

​
Leggi anche