Panoramica delle integrazioni

CodeCourier si basa su un insieme accuratamente selezionato di servizi di terze parti, ciascuno dei quali fornisce una capacità critica che sarebbe impraticabile costruire internamente. Invece di un’infrastruttura monolitica, CodeCourier segue un’architettura componibile in cui ogni integrazione gestisce un’unica area, e la gestisce in modo eccezionale. Questa pagina offre una panoramica di ogni integrazione, di cosa fornisce e di come i vari pezzi si incastrano tra loro.

Architettura delle integrazioni

Il flusso di dati della piattaforma può essere compreso in quattro livelli:

1. Livello di autenticazione (Clerk) -- Gestisce la registrazione, l’accesso, la gestione delle sessioni e l’identità. Clerk emette JWT che Convex convalida a ogni chiamata di funzione.
2. Livello dati (Convex) -- Il database reattivo che memorizza tutto lo stato dell’applicazione: utenti, progetti, sandbox, workflow, run, messaggi, learning e registri di utilizzo. Convex fornisce sottoscrizioni in tempo reale in modo che la dashboard si aggiorni istantaneamente quando i dati cambiano.
3. Livello di esecuzione (E2B) -- Fornisce macchine virtuali Linux cloud isolate in cui girano gli agenti di coding IA. E2B gestisce il provisioning delle VM, l’accesso al file system, l’esecuzione dei processi e la gestione della rete.
4. Livello di orchestrazione (Trigger.dev) -- Gestisce i job in background di lunga durata che coordinano l’intero workflow: provisioning delle sandbox, invio dei prompt, iterazioni designer-checker, estrazione dei learning e creazione delle pull request.

Integrazioni disponibili

Sandbox E2B

E2B fornisce gli ambienti di esecuzione cloud isolati che sono il cuore di CodeCourier. Ogni sandbox è una micro-VM E2B con un proprio kernel Linux, file system e stack di rete. L’SDK E2B (versione 2.14+) viene usato per creare, connettersi e gestire il ciclo di vita delle sandbox.

Leggi la guida all’integrazione E2B

Trigger.dev

Trigger.dev gestisce tutta l’elaborazione dei job in background. L’orchestrazione dei workflow, l’esecuzione delle work chain, le issue session, la issue discovery, l’estrazione dei learning e le operazioni del merge agent girano tutte come task Trigger.dev. Questo mantiene il backend Convex reattivo mentre le operazioni IA di lunga durata vengono eseguite in modo asincrono.

Leggi la guida all’integrazione Trigger.dev

Autenticazione Clerk

Clerk fornisce un’autenticazione pronta all’uso con supporto per email e password, provider OAuth (Google, GitHub) e magic link. L’SDK @clerk/nextjs (versione 6+) si integra direttamente con l’app router di Next.js, e i JWT di Clerk vengono passati a Convex per la verifica dell’identità lato server.

Leggi la guida all’integrazione Clerk

Database Convex

Convex è la piattaforma di database reattivo che alimenta tutto l’archivio dati e le funzionalità in tempo reale. Le query si rieseguono automaticamente quando i dati sottostanti cambiano, le mutation sono transazionali e le action offrono un modo per chiamare servizi esterni. Lo schema Convex definisce tutte le tabelle, gli indici e le regole di validazione.

Leggi la guida all’integrazione Convex

Come vengono configurate le integrazioni

Ogni integrazione richiede una configurazione specifica, tipicamente tramite variabili d’ambiente. Ecco un riepilogo di ciò di cui ogni integrazione ha bisogno:

Variabili d’ambiente richieste

• Convex -- CONVEX_DEPLOYMENT e NEXT_PUBLIC_CONVEX_URL vengono impostate automaticamente durante la configurazione del progetto.
• Clerk -- NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY e CLERK_SECRET_KEY dalla dashboard Clerk. CLERK_WEBHOOK_SECRET per la verifica dei webhook.
• Trigger.dev -- TRIGGER_SECRET_KEY per l’SDK Trigger.dev, TRIGGER_CALLBACK_SECRET per callback sicuri verso Convex.
• E2B -- Gli utenti forniscono la propria chiave API E2B tramite la dashboard, che viene criptata e memorizzata nel database. Non è necessaria alcuna configurazione E2B a livello server.

Chiavi API fornite dall’utente

Oltre alla configurazione a livello server, singoli utenti o progetti possono fornire le proprie chiavi API per i servizi che le sandbox usano a runtime:

• Chiave API E2B -- Richiesta per il provisioning delle sandbox.
• Chiave API o token Anthropic -- Richiesto per le sandbox Claude Code.
• Chiave API OpenRouter -- Per l’accesso ai modelli tramite OpenRouter.
• Chiave API OpenAI -- Per Codex e gli strumenti basati su OpenAI.
• Token GitHub -- Per le operazioni sui repository all’interno delle sandbox.

Queste chiavi possono essere impostate a livello utente (valide per tutti i progetti) o a livello progetto (sovrascrivono le chiavi a livello utente per quel progetto specifico). Tutte le chiavi vengono criptate prima della memorizzazione.

Dipendenze tra integrazioni

Le integrazioni hanno relazioni di dipendenza specifiche:

• Clerk dipende da Convex -- I JWT di Clerk vengono convalidati da Convex. La tabella utenti in Convex memorizza la mappatura tra gli ID Clerk e gli ID utente interni.
• Trigger.dev dipende da Convex -- Tutti i task Trigger.dev riportano l’avanzamento a Convex tramite l’endpoint di callback HTTP.
• E2B dipende da Trigger.dev -- Il provisioning e la gestione delle sandbox avvengono all’interno dei task Trigger.dev. Le operazioni E2B non vengono mai chiamate direttamente dal browser.
• Convex è il fulcro centrale -- Tutti gli altri servizi comunicano tramite Convex, che diventa così l’archivio dati centrale e il punto di coordinamento.

Versioni dei pacchetti

CodeCourier utilizza le seguenti versioni dei pacchetti di integrazione (controlla package.json per le versioni più recenti):

• convex -- ^1.32.0
• @clerk/nextjs -- ^6.39.0
• e2b -- ^2.14.0
• @trigger.dev/sdk -- 4.4.3
• @trigger.dev/react-hooks -- 4.4.3
• @anthropic-ai/sdk -- ^0.78.0