Übersicht der Starter Application

Die Copera Starter Application (auch Base Application genannt) ist eine Open-Source-Referenzimplementierung, die Entwicklern genau zeigt, wie man eine voll funktionsfähige, produktionsreife Anwendung auf Copera Boards mit dem @copera.ai/sdk baut. Das ist der schnellste Weg von null zu einer laufenden Custom-App, die von Ihren Copera-Daten angetrieben wird.

Was ist die Starter Application?

Im Kern behandelt die Starter Application Ihr Copera Board als Datenbank. Jede Tabelle in Ihrem Board ist eine Datenquelle, jede Zeile ein Datensatz und jede Spalte ein Feld. Das @copera.ai/sdk liefert eine saubere TypeScript-API zum Lesen, Schreiben, Aktualisieren und Löschen von Zeilen — kein SQL, kein eigenes Backend-Schema. Ihr Board ist die Single Source of Truth.

Die Referenzimplementierung kommt als Help Center / Support-Ticket-Portal: Benutzer können sich anmelden, Tickets einreichen und ihre Ticket-Historie ansehen. Das ist nur ein Beispiel. Weil die darunterliegende Mechanik generisch ist, können Sie denselben Code anpassen, um praktisch jede Anwendung zu bauen, die Ihre Kunden brauchen.

tipp

Betrachten Sie die Starter Application als leere Leinwand mit bereits verlegter Plumbing. Tauschen Sie die Ticket-Tabellen gegen Produktkataloge, Stellenangebote, Mitarbeiterdatensätze oder Service-Anfragen — die Architektur bleibt gleich.

Was Sie bauen können

Beispiele für Anwendungen, die Kunden auf Copera Boards gebaut haben oder bauen:

Anwendungstyp	Board als Datenbank
Help Center / Support-Portal	Tickets-Tabelle, Users-Tabelle, Status-Spalte
E-Commerce-Storefront	Products-Tabelle, Orders-Tabelle, Inventory-Spalten
HR-Mitarbeiterportal	Employees-Tabelle, Departments-Tabelle, Leave-Requests-Tabelle
Kunden-Projektportal	Projects-Tabelle, Tasks-Tabelle, Milestones-Tabelle
Knowledge Base / FAQ	Articles-Tabelle, Categories-Tabelle, Tags-Spalte
Event-Registrierungssystem	Events-Tabelle, Registrants-Tabelle, Attendance-Spalte

Jeder strukturierte Datensatz, der in ein Copera Board passt, kann Backend einer custom-gebrandeten Anwendung werden.

Architektur

Die Starter Application ist in zwei separate Packages aufgeteilt, die zusammenarbeiten:

base-application-api

Eine REST-API zwischen Ihrem Frontend und Copera. Sie übernimmt Authentifizierung, validiert Anfragen, schreibt Daten über das SDK in Ihr Copera Board und cached Datensätze lokal in der Datenbank für schnelle Reads.

Kernaufgaben:

• Authentifizierung — JWT-basiertes Sign-in mit Board-Zeilen als User-Store. Die SDK-Methode authenticateTableRow validiert Credentials direkt gegen die Spalten Ihrer Users-Tabelle.
• SDK-Integration — Alle Board-Operationen (Zeile anlegen, listen, aktualisieren) laufen über das @copera.ai/sdk. Sie konfigurieren Board- und Tabellen-IDs in einer einzigen Datei config.ts.
• Lokales Caching — Nach dem Schreiben einer Zeile nach Copera speichert die API eine leichte Kopie in der Datenbank. List-Queries sind so schnelle lokale Reads statt Roundtrips zur Copera API bei jeder Anfrage.
• Standard-REST-Endpunkte — Controller folgen einem sauberen, klassenbasierten Muster, sodass neue Ressourcentypen einfach hinzugefügt werden können.

Tech-Stack: ein Node.js-REST-Framework, eine Dokumentdatenbank, JWT-Authentifizierung mit verschlüsselten Credentials, @copera.ai/sdk, Pino-Logging, Yup/Zod-Validierung.

base-application-web

Eine React-Single-Page-Application, die die Benutzeroberfläche liefert. Sie kommuniziert ausschließlich mit base-application-api und berührt Copera nie direkt.

Kernaufgaben:

• Auth-Flow — Ein context-basierter AuthProvider speichert das JWT, schützt geschützte Routes und leitet nicht authentifizierte Benutzer zur Sign-in-Seite um.
• Data Fetching — React Query verwaltet den gesamten Server-State inkl. Caching, Refetching und optimistischer Updates. Query-Keys sind zentral für konsistentes Cache-Management.
• UI-Komponenten — Gebaut mit einer barrierefreien Component-Library (Radix-UI-Primitives) und gestylt mit einem utility-first CSS-Framework — moderne, zugängliche UI out of the box.
• Client-State — Zustand übernimmt leichten UI-State wie Sidebar-Sichtbarkeit und ausgewählte Einträge.

Tech-Stack: React 18, modernes Build-Tool, utility-first CSS-Framework, barrierefreie Component-Library, React Query (TanStack Query 5), Zustand 4, React Hook Form 7, React Router 7.

So funktioniert der Datenfluss

Den Datenfluss zu verstehen ist der Schlüssel, um die Starter Application für Ihren Use Case anzupassen:

1. Ein Benutzer interagiert mit dem React-Frontend — z. B. ein neues Support-Ticket absenden.
2. Das Frontend sendet eine POST-Anfrage an base-application-api mit den Formulardaten.
3. Die API schreibt die Zeile nach Copera über das SDK: copera.board.tables.<tableName>.createRow({ ... }).
4. Die API speichert einen Cache-Datensatz in einer lokalen Datenbank, mit der Copera-Zeilen-ID und lokal benötigten Feldern.
5. Die API gibt den neuen Datensatz an das Frontend zurück, wo React Query die gecachte Liste sofort aktualisiert.
6. Ihr Team sieht das Ticket in Copera — im Board, in der richtigen Tabelle, bereit für Coperas eingebaute Tools: Views, Automatisierungen, KI-Features und mehr.

Dieses Muster bedeutet: Ihre Kunden nutzen eine saubere Custom-Oberfläche, während Ihr internes Team in Copera mit den bekannten Tools arbeitet.

Board-Konfiguration

Die gesamte Board-Verbindung steuert ein einziges Konfigurationsobjekt in der API. Sie liefern Ihre Board-ID und die Tabellen-IDs für jeden Datentyp Ihrer Anwendung. Spalten-IDs sagen dem SDK, welche Spalten gelesen und geschrieben werden.

// 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',
  },
};

Siehe die Seite Spalten-IDs finden, um die richtigen IDs für Tabellen und Spalten Ihres Boards zu finden.

Open Source

Die Starter Application wird als Open Source auf GitHub veröffentlicht. Sie dürfen sie forken, anpassen und nach Belieben deployen. Sie ist einfach genug, um sie schnell zu verstehen, und strukturiert genug, um mit Ihren Produktanforderungen zu skalieren.

Nächste Schritte

• Erste Schritte — Die Starter Application lokal in unter 15 Minuten einrichten.
• Mit KI-Tools bauen — Erfahren Sie, wie KI-Coding-Assistenten die Entwicklung auf der Starter Application beschleunigen.
• Spalten-IDs finden — Board-ID, Tabellen-IDs und Spalten-IDs für die SDK-Konfiguration finden.