Project Structure

A Qumra app is a full-stack React application built with React Router v7, Vite, and Prisma.

Directory Overview

my-qumra-app/
├── app/                            # Application source code
│   ├── components/                 # Reusable React components
│   │   ├── LoadingSpinner.tsx      # Loading indicator
│   │   └── ProgressBar.tsx         # Navigation progress bar
│   ├── routes/                     # File-based routes (React Router v7)
│   │   ├── _index.tsx              # Root route (/)
│   │   ├── auth.$.tsx              # OAuth callback handler (/auth/*)
│   │   ├── home.tsx                # Home page (/home)
│   │   ├── about.tsx               # About page (/about)
│   │   ├── settings.tsx            # Settings page (/settings)
│   │   └── product-create.tsx      # Webhook handler (/product-create)
│   ├── utils/                      # Utility functions and hooks
│   │   └── useIframeNavigation.tsx # Iframe navigation hook
│   ├── qumra.server.ts            # Qumra SDK initialization (server-only)
│   ├── root.tsx                    # Root layout component
│   ├── routes.ts                   # Route configuration
│   └── app.css                     # Global styles (TailwindCSS)
├── prisma/                         # Database layer
│   ├── lib/
│   │   └── prisma.ts              # Prisma client initialization
│   ├── migrations/                # Database migrations
│   └── schema.prisma              # Database schema
├── .qumra/
│   └── qumra.config.json          # Qumra app config (auto-generated)
├── qumra.app.json                 # App manifest
├── vite.config.ts                 # Vite configuration
├── react-router.config.ts         # React Router configuration
├── Dockerfile                     # Docker deployment
└── package.json                   # Dependencies and scripts

Key Directories

app/

The main application directory containing all your React components, routes, utilities, and styles. This is where you spend most of your development time.

app/routes/

File-based routing powered by React Router v7. Each file in this directory becomes a route in your application:

File	URL Path	Purpose
_index.tsx	/	Root route, handles initial app load and auth redirect
auth.$.tsx	/auth/*	OAuth callback handler (splat route)
home.tsx	/home	Main app dashboard after authentication
about.tsx	/about	About page
settings.tsx	/settings	App settings management
product-create.tsx	/product-create	Webhook endpoint for product creation events

File-Based Routing

Qumra apps use React Router v7's file-based routing convention. The file name determines the URL path automatically. For example, app/routes/settings.tsx maps to /settings. Nested routes use dot notation -- auth.$.tsx matches /auth/* as a splat route. See the Routing guide for more details.

app/components/

Reusable React components shared across routes. The scaffold includes common components like loading spinners and progress bars. Add your own components here as your app grows.

prisma/

The database layer powered by Prisma ORM. Contains the schema definition, migrations, and the Prisma client initialization. By default, Qumra apps use SQLite for development, making it easy to get started without any external database setup.

.qumra/

Auto-generated configuration directory managed by the Qumra CLI. Contains qumra.config.json which stores your app's connection details to the Qumra platform.

warning

Do not manually edit files in the .qumra/ directory. These are managed by the CLI and may be overwritten.

Key Files

qumra.app.json

The App Manifest file that defines your app's metadata, permissions (scopes), and webhook subscriptions. This is the central configuration file for your app's relationship with the Qumra platform.

qumra.app.json

{
  "scopes": ["read_products", "write_products"],
  "webhooks": {
    "api_version": "",
    "subscriptions": [
      {
        "topics": ["product/create"],
        "uri": "/product-create"
      }
    ]
  },
  "productionUrl": ""
}

app/qumra.server.ts

The server-side App Framework initialization file. This module configures the SDK with your API credentials and exports the authenticated client for use in route loaders and actions.

app/qumra.server.ts

import { qumraApp, AppDistribution } from "@qumra/app-react-router";
import { PrismaSessionStorage } from "@qumra/app-session-storage-prisma";
import { prisma } from "../prisma/lib/prisma";

const qumra = qumraApp({
  apiKey: process.env.QUMRA_API_KEY!,
  secretKey: process.env.QUMRA_API_SECRET!,
  appUrl: process.env.QUMRA_APP_URL!,
  sessionStorage: new PrismaSessionStorage(prisma),
  distribution: AppDistribution.AppStore,
});

export default qumra;
export const authenticate = qumra.authenticate;

vite.config.ts

The Vite build configuration, pre-configured with HMR settings for iframe development and CORS headers. See the Configuration guide for details.

Dockerfile

A production-ready Docker configuration for deploying your app to any container hosting platform.

Scripts

The package.json includes these development scripts:

Script	Command	Description
dev	qumra app dev	Start the development server with HMR
build	react-router build	Build for production
start	react-router-serve ./build/server/index.js	Start the production server
typecheck	react-router typegen && tsc	Run TypeScript type checking
db:migrate	npx prisma migrate deploy	Apply database migrations
db:studio	npx prisma studio	Open Prisma Studio GUI