Vue d'ensemble de la Starter Application

La Copera Starter Application (aussi appelée Base Application) est une implémentation de référence open source qui montre aux développeurs exactement comment construire une application pleinement fonctionnelle et prête pour la production au-dessus des Boards Copera en utilisant le @copera.ai/sdk. C'est le chemin le plus rapide de zéro à une app personnalisée fonctionnelle alimentée par vos données Copera.

Qu'est-ce que la Starter Application ?

À la base, la Starter Application traite votre Board Copera comme une base de données. Chaque table de votre board est une source de données, chaque ligne est un enregistrement, et chaque colonne est un champ. Le @copera.ai/sdk fournit une API TypeScript propre pour lire, écrire, mettre à jour et supprimer des lignes — pas de SQL, pas de schéma backend personnalisé requis. Votre board est la source unique de vérité.

L'implémentation de référence est livrée comme un portail Help Center / Support Ticket : les utilisateurs peuvent se connecter, soumettre des tickets, et consulter l'historique de leurs tickets. Mais ce n'est qu'un exemple. Comme les mécaniques sous-jacentes sont génériques, vous pouvez adapter le même codebase pour construire pratiquement n'importe quelle application dont vos clients ont besoin.

astuce

Pensez à la Starter Application comme une toile blanche avec la plomberie déjà en place. Remplacez les tables de tickets par des catalogues produits, des offres d'emploi, des dossiers employés ou des demandes de service — l'architecture reste la même.

Ce que vous pouvez construire

Voici des exemples d'applications que des clients ont construites ou construisent au-dessus des Boards Copera :

Type d'application	Board comme base de données
Help Center / Portail de support	Table Tickets, table Users, colonne Status
Vitrine e-commerce	Table Products, table Orders, colonnes Inventory
Portail RH employés	Table Employees, table Departments, table Leave Requests
Portail projet orienté client	Table Projects, table Tasks, table Milestones
Base de connaissances / FAQ	Table Articles, table Categories, colonne Tags
Système d'inscription à des événements	Table Events, table Registrants, colonne Attendance

Tout ensemble de données structurées qui tient dans un Board Copera peut devenir le backend d'une application à la marque personnalisée.

Architecture

La Starter Application est divisée en deux packages distincts qui fonctionnent ensemble :

base-application-api

Une API REST qui se place entre votre frontend et Copera. Elle gère l'authentification, valide les requêtes, écrit les données dans votre Board Copera via le SDK, et met en cache les enregistrements localement dans la base de données pour des lectures rapides.

Responsabilités clés :

• Authentification — connexion basée sur JWT en utilisant les lignes du board comme magasin d'utilisateurs. La méthode authenticateTableRow du SDK valide les identifiants directement contre les colonnes de votre table Users.
• Intégration SDK — Toutes les opérations board (créer une ligne, lister les lignes, mettre à jour une ligne) passent par le @copera.ai/sdk. Vous configurez quels IDs de board et de table utiliser dans un seul fichier config.ts.
• Cache local — Après avoir écrit une ligne dans Copera, l'API enregistre une copie légère dans la base de données. Cela signifie que les requêtes de liste sont des lectures locales rapides plutôt que des allers-retours vers l'API Copera à chaque requête.
• Endpoints REST standard — Les contrôleurs suivent un motif propre, basé sur des classes, ce qui facilite l'ajout de nouveaux types de ressources.

Stack technique : un framework REST Node.js, une base de données document, l'authentification JWT avec identifiants chiffrés, @copera.ai/sdk, journalisation Pino, validation Yup/Zod.

base-application-web

Une application monopage React qui fournit l'interface utilisateur. Elle communique exclusivement avec base-application-api et ne touche jamais Copera directement.

Responsabilités clés :

• Flux d'authentification — Un AuthProvider basé sur le contexte stocke le JWT, protège les routes protégées, et redirige les utilisateurs non authentifiés vers la page de connexion.
• Récupération de données — React Query gère tout l'état serveur, y compris le cache, le refetch et les mises à jour optimistes. Les clés de requête sont centralisées pour une gestion de cache cohérente.
• Composants UI — Construits avec une bibliothèque de composants accessible (primitives Radix UI) et stylés avec un framework CSS utility-first, pour une UI moderne et accessible dès le départ.
• État client — Zustand gère l'état UI léger comme la visibilité de la barre latérale et les éléments sélectionnés.

Stack technique : React 18, un outil de build moderne, un framework CSS utility-first, une bibliothèque de composants accessible, React Query (TanStack Query 5), Zustand 4, React Hook Form 7, React Router 7.

Comment fonctionne le flux de données

Comprendre le flux de données est la clé pour personnaliser la Starter Application pour votre propre cas d'usage :

1. Un utilisateur interagit avec le frontend React — par exemple, en soumettant un nouveau ticket de support.
2. Le frontend envoie une requête POST à base-application-api avec les données du formulaire.
3. L'API écrit la ligne dans Copera via le SDK : copera.board.tables.<tableName>.createRow({ ... }).
4. L'API enregistre un enregistrement en cache dans une base de données locale, en stockant l'ID de ligne Copera aux côtés de tout champ nécessaire localement.
5. L'API renvoie le nouvel enregistrement au frontend, où React Query met à jour immédiatement la liste en cache.
6. Votre équipe voit le ticket dans Copera — dans son board, dans la bonne table, prêt à être géré avec tous les outils intégrés de Copera : vues, automatisations, fonctionnalités IA, et plus.

Ce motif signifie que vos clients interagissent avec une interface personnalisée propre, tandis que votre équipe interne travaille dans Copera avec tous les outils qu'elle connaît déjà.

Configuration du board

Toute la connexion au board est contrôlée par un seul objet de configuration dans l'API. Vous fournissez votre Board ID et les Table IDs pour chaque type de données que votre application utilise. Les Column IDs indiquent au SDK quelles colonnes spécifiques lire et écrire.

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

Voir la page Trouver les Column IDs pour apprendre à trouver les bons IDs pour les tables et colonnes de votre board.

Open source

La Starter Application sera publiée en open source sur GitHub. Vous êtes libre de la forker, de la modifier et de la déployer comme vous le souhaitez. Elle est conçue pour être assez simple à comprendre rapidement et assez structurée pour évoluer avec les exigences de votre produit.

Prochaines étapes

• Premiers pas — Configurez la Starter Application en local en moins de 15 minutes.
• Construire avec des outils IA — Apprenez à utiliser des assistants de code IA pour accélérer le développement au-dessus de la Starter Application.
• Trouver les Column IDs — Trouvez le Board ID, les Table IDs et les Column IDs dont vous avez besoin pour configurer le SDK.