> ## Documentation Index
> Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Architettura per contributori

> Struttura del repo e confini di runtime per i contributori.

# 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

* [Sviluppo](/it/development)
* [Confine di persistenza](/it/contributing/persistence)
* [Architettura della piattaforma](/it/platform/architecture)
* [Flusso di contribuzione](/it/contributing/workflow)