Panoramica della Starter Application

La Copera Starter Application (chiamata anche Base Application) è un'implementazione di riferimento open-source che mostra agli sviluppatori esattamente come costruire un'applicazione pienamente funzionale e production-ready sopra le Copera Boards usando @copera.ai/sdk. È il percorso più veloce da zero a un'app custom funzionante alimentata dai tuoi dati Copera.

Cos'è la Starter Application?

Nel nucleo, la Starter Application tratta la tua Copera Board come un database. Ogni table nella board è una data source, ogni riga è un record e ogni colonna è un field. @copera.ai/sdk fornisce un'API TypeScript pulita per leggere, scrivere, aggiornare ed eliminare righe — niente SQL, nessuno schema backend custom richiesto. La board è la single source of truth.

L'implementazione di riferimento arriva come Help Center / Support Ticket portal: gli utenti possono accedere, inviare ticket e vedere la cronologia dei ticket. Ma questo è solo un esempio. Poiché le meccaniche sottostanti sono generiche, puoi adattare lo stesso codebase per costruire praticamente qualsiasi applicazione di cui i clienti hanno bisogno.

suggerimento

Pensa alla Starter Application come a una tela bianca con l'impianto già in posto. Sostituisci le table dei ticket con cataloghi prodotti, job listing, record dipendenti o service request — l'architettura resta la stessa.

Cosa puoi costruire

Ecco esempi di applicazioni che i clienti hanno costruito o stanno costruendo sopra le Copera Boards:

Application Type	Board as Database
Help Center / Support Portal	Tickets table, Users table, Status column
E-commerce Storefront	Products table, Orders table, Inventory columns
HR Employee Portal	Employees table, Departments table, Leave Requests table
Client-facing Project Portal	Projects table, Tasks table, Milestones table
Knowledge Base / FAQ	Articles table, Categories table, Tags column
Event Registration System	Events table, Registrants table, Attendance column

Qualsiasi dataset strutturato che sta in una Copera Board può diventare il backend di un'applicazione custom-branded.

Architettura

La Starter Application è suddivisa in due package separati che lavorano insieme:

base-application-api

Una REST API che si interpone tra il frontend e Copera. Gestisce l'autenticazione, valida le request, scrive i dati sulla Copera Board tramite l'SDK e mette in cache i record in locale nel database per letture veloci.

Responsabilità chiave:

• Authentication — sign-in basato su JWT usando le righe di board come user store. Il metodo authenticateTableRow dell'SDK valida le credenziali direttamente contro le colonne della table Users.
• SDK integration — Tutte le operazioni board (create row, list rows, update row) passano da @copera.ai/sdk. Configuri quali board e table ID usare in un unico file config.ts.
• Local caching — Dopo aver scritto una riga su Copera, l'API salva una copia leggera nel database. Questo significa che le query di list sono letture locali veloci anziché round-trip all'API Copera a ogni richiesta.
• Standard REST endpoints — I controller seguono un pattern pulito basato su classi, rendendo semplice aggiungere nuovi tipi di risorsa.

Tech stack: un framework REST Node.js, un document database, autenticazione JWT con credenziali criptate, @copera.ai/sdk, logging Pino, validazione Yup/Zod.

base-application-web

Una React single-page application che fornisce l'interfaccia utente. Comunica esclusivamente con base-application-api e non tocca mai Copera direttamente.

Responsabilità chiave:

• Authentication flow — Un AuthProvider basato su context memorizza il JWT, protegge le route e reindirizza gli utenti non autenticati alla pagina di sign-in.
• Data fetching — React Query gestisce tutto lo server state, inclusa cache, refetch e optimistic update. Le query key sono centralizzate per una gestione coerente della cache.
• UI components — Costruiti con una component library accessibile (primitivi Radix UI) e stilizzati con un framework CSS utility-first, dandoti una UI moderna e accessibile out of the box.
• Client state — Zustand gestisce lo stato UI leggero come la visibility della sidebar e gli item selezionati.

Tech stack: React 18, un modern build tool, un framework CSS utility-first, una component library accessibile, React Query (TanStack Query 5), Zustand 4, React Hook Form 7, React Router 7.

Come funziona il data flow

Comprendere il data flow è la chiave per personalizzare la Starter Application per il tuo caso d'uso:

1. Un utente interagisce con il frontend React — ad esempio, inviando un nuovo support ticket.
2. Il frontend invia una POST request a base-application-api con i dati del form.
3. L'API scrive la riga su Copera tramite l'SDK: copera.board.tables.<tableName>.createRow({ ... }).
4. L'API salva un record di cache in un database locale, memorizzando il Copera row ID insieme a qualsiasi field necessario in locale.
5. L'API restituisce il nuovo record al frontend, dove React Query aggiorna immediatamente la lista in cache.
6. Il team vede il ticket in Copera — nella board, nella table corretta, pronto per essere gestito con tutti i tool built-in di Copera: view, automazioni, feature IA e altro.

Questo pattern significa che i clienti interagiscono con un'interfaccia custom pulita, mentre il team interno lavora dentro Copera usando tutti i tool che già conosce.

Configurazione della Board

L'intera connessione alla board è controllata da un singolo oggetto di configurazione nell'API. Fornisci il Board ID e i Table ID per ogni tipo di dato che l'applicazione usa. I Column ID dicono all'SDK quali colonne specifiche leggere e scrivere.

// apps/base-application-api/src/config.ts
export const COPERA_CONFIG = {
  boardId: 'your-board-id',
  usersTable: {
    usersTableId: 'your-users-table-id',
    identifierColumnId: 'email-column-id',
    passwordColumnId: 'password-column-id',
  },
  ticketsTable: {
    ticketsTableId: 'your-tickets-table-id',
  },
};

Vedi la pagina Trovare i Column ID per imparare come trovare gli ID corretti per le table e le colonne della board.

Open Source

La Starter Application sarà pubblicata come open source su GitHub. Sei libero di farne fork, modificarla e deployarla come preferisci. È progettata per essere abbastanza semplice da capire rapidamente e abbastanza strutturata da scalare con i requisiti del prodotto.

Prossimi passi

• Primi passi — Configura la Starter Application in locale in meno di 15 minuti.
• Costruire con tool IA — Impara come usare gli assistenti di coding con IA per accelerare lo sviluppo sopra la Starter Application.
• Trovare i Column ID — Trova Board ID, Table ID e Column ID di cui hai bisogno per configurare l'SDK.