Starter Application Overview

The Copera Starter Application (also called the Base Application) is an open-source reference implementation that shows developers exactly how to build a fully functional, production-ready application on top of Copera Boards using the @copera.ai/sdk. It is the fastest path from zero to a working custom app powered by your Copera data.

What Is the Starter Application?

At its core, the Starter Application treats your Copera Board as a database. Every table in your board is a data source, every row is a record, and every column is a field. The @copera.ai/sdk provides a clean TypeScript API to read, write, update, and delete rows — no SQL, no custom backend schema required. Your board is the single source of truth.

The reference implementation ships as a Help Center / Support Ticket portal: users can sign in, submit tickets, and view their ticket history. But this is just one example. Because the underlying mechanics are generic, you can adapt the same codebase to build virtually any application your customers need.

tip

Think of the Starter Application as a blank canvas with the plumbing already in place. Swap out the ticket tables for product catalogs, job listings, employee records, or service requests — the architecture stays the same.

What You Can Build

Here are examples of applications customers have built or are building on top of 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

Any structured dataset that fits inside a Copera Board can become the backend for a custom-branded application.

Architecture

The Starter Application is split into two separate packages that work together:

base-application-api

A Fastify REST API that sits between your frontend and Copera. It handles authentication, validates requests, writes data to your Copera Board via the SDK, and caches records locally in MongoDB for fast reads.

Key responsibilities:

• Authentication — JWT-based sign-in using board rows as the user store. The SDK's authenticateTableRow method validates credentials directly against your Users table columns.
• SDK integration — All board operations (create row, list rows, update row) go through the @copera.ai/sdk. You configure which board and which table IDs to use in a single config.ts file.
• Local caching — After writing a row to Copera, the API saves a lightweight copy to MongoDB. This means list queries are fast local reads rather than round-trips to the Copera API on every request.
• Standard REST endpoints — Controllers follow a clean class-based pattern using fastify-decorators, making it straightforward to add new resource types.

Tech stack: Fastify 4, MongoDB (Typegoose), JWT + AES-CBC encryption, @copera.ai/sdk, Pino logging, Yup/Zod validation.

base-application-web

A React single-page application that provides the user interface. It communicates exclusively with base-application-api and never touches Copera directly.

Key responsibilities:

• Authentication flow — A context-based AuthProvider stores the JWT, guards protected routes, and redirects unauthenticated users to the sign-in page.
• Data fetching — React Query manages all server state, including caching, refetching, and optimistic updates. Query keys are centralized for consistent cache management.
• UI components — Built with shadcn/ui (Radix UI primitives) and styled with Tailwind CSS, giving you a modern, accessible component library out of the box.
• Client state — Zustand handles lightweight UI state such as sidebar visibility and selected items.

Tech stack: React 18, Vite 6, Tailwind CSS 4, shadcn/ui, React Query (TanStack Query 5), Zustand 4, React Hook Form 7, React Router 7.

How the Data Flow Works

Understanding the data flow is the key to customizing the Starter Application for your own use case:

1. A user interacts with the React frontend — for example, submitting a new support ticket.
2. The frontend sends a POST request to base-application-api with the form data.
3. The API writes the row to Copera via the SDK: copera.board.tables.<tableName>.createRow({ ... }).
4. The API saves a cache record in local MongoDB, storing the Copera row ID alongside any locally needed fields.
5. The API returns the new record to the frontend, where React Query updates the cached list immediately.
6. Your team sees the ticket in Copera — in their board, in the correct table, ready to be managed with all of Copera's built-in tools: views, automations, AI features, and more.

This pattern means your customers interact with a clean custom interface, while your internal team works inside Copera using all the tools they already know.

Board Configuration

The entire board connection is controlled by a single configuration object in the API. You provide your Board ID and the Table IDs for each data type your application uses. Column IDs tell the SDK which specific columns to read and write.

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

See the Column IDs page to learn how to find the correct IDs for your board's tables and columns.

Open Source

The Starter Application will be published as open source on GitHub. You are free to fork it, modify it, and deploy it however you like. It is designed to be simple enough to understand quickly and structured enough to scale with your product requirements.

Next Steps

• Getting Started — Set up the Starter Application locally in under 15 minutes.
• Using AI to Build — Learn how to use AI coding assistants to accelerate development on top of the Starter Application.
• Column IDs — Find the Board ID, Table IDs, and Column IDs you need to configure the SDK.