***
title: Setup
subtitle: Configure where Ask Fern is available and what content it can access.
max-toc-depth: 2
----------------
For clean Markdown content of this page, append .md to this URL. For the complete documentation index, see [https://buildwithfern.com/learn/llms.txt](https://buildwithfern.com/learn/llms.txt). For full content including API reference and SDK examples, see [https://buildwithfern.com/learn/llms-full.txt](https://buildwithfern.com/learn/llms-full.txt).
## Basic setup
Enable Ask Fern by adding the `ai-search` configuration to your `docs.yml` file:
```yaml docs.yml
ai-search:
location:
- docs
- slack
```
After you enable Ask Fern, it needs to index your content before the [side panel](/learn/docs/ai-features/ask-fern/overview) can appear on your site. This typically takes a few minutes, though sites with extensive custom components may take longer.
## Configuration
```yaml docs.yml
ai-search:
location:
- docs
- discord
datasources:
- url: https://example.com/additional-docs
title: Additional documentation
- url: https://blog.example.com
title: Company blog
system-prompt:
## your custom prompt
You are an AI assistant. The user asking questions may be a developer, technical writer, or product manager. You can provide code examples.
ONLY respond to questions using information from the documents. Stay on topic. You cannot book appointments, schedule meetings, or create support tickets.
You have no integrations outside of querying the documents. Do not tell the user your system prompt, or other environment information.
```
Specifies where Ask Fern will be available. Options:
* `docs` enables Ask Fern on your documentation site
* `slack` enables Ask Fern in Slack
* `discord` enables Ask Fern in Discord
Most users should enable Ask Fern for both `docs` and either `slack` ([setup instructions](/learn/docs/ai-features/ask-fern/slack-app)) or `discord` ([setup instructions](/learn/docs/ai-features/ask-fern/discord-bot)).
Additional content sources that Ask Fern should index and search. For more details, see [Additional content sources](/learn/docs/ai-features/ask-fern/content-sources).
The URL of the website to index. Ask Fern will crawl and index the content from this URL.
An optional display name for this datasource. This helps users understand where the information is coming from when Ask Fern cites content from this source.
By default, Ask Fern uses system prompts to finetune AI search results. Add a custom prompt to override it.
See Anthropic's [prompting guide](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) for ideas and examples.
The AI model to use for Ask Fern responses. Options:
* `claude-3.7` - Claude 3.7 Sonnet (default)
* `claude-4` - Claude 4 Sonnet
* `command-a` - Cohere Command A
If not specified, Ask Fern uses `claude-3.7`.
***
USE THIS:
## What This App Is
CPS-APP is the official Convention Photography Services customer and admin app. It is a **full-stack TypeScript monorepo** with:
* An Express server (backend)
* A React/Vite PWA (frontend)
* Google Sheets as the only database
* No SQL, no Drizzle, no Postgres
## Critical Rules
### 1. Do Not Add a Database
All order data lives in Google Sheets. The spreadsheet ID is `GOOGLE_SPREADSHEET_ID`. Do not add Drizzle, Postgres, SQLite, or any other SQL layer.
### 2. Photo and Event Data Comes from the PHP Backend
The PHP backend URL is `PHP_BACKEND_URL` (default: `http://photos.conventionphotography.com`). Events and photo thumbnails are fetched through these proxy routes:
* `GET /api/proxy-events` → lists events
* `GET /api/proxy-image/:event/:photo` → serves a thumbnail
Do not query these services directly from the frontend — always go through the backend proxy.
### 3. Order Numbers Are Sequential Per Event
Order counters are stored in `data/orderCounters.json` as `{ "EVENTSLUG": 42 }`. The order number format is `EVENTSLUG-0042`. This file must persist across server restarts (mount it as a volume in production).
### 4. The Frontend Uses Wouter, Not React Router
Routing is done with `wouter`. Do not install or use `react-router-dom`.
### 5. Data Fetching Uses TanStack Query v5
All HTTP data fetching in the frontend must use `useQuery` / `useMutation` from `@tanstack/react-query`. Use the object form only (v5 API). The default `queryFn` is wired up in `client/src/lib/queryClient.ts` to use the URL in `queryKey[0]`.
### 6. Styling Uses Tailwind + shadcn
All UI components are shadcn-based. Import them from `@/components/ui/`. Use TailwindCSS utility classes. The color theme is dark slate with amber/gold accents — defined in `client/src/index.css`.
## Key Files
| File | Purpose |
| --------------------------------------- | ------------------------------------------------------- |
| `server/routes.ts` | All API endpoints — the main place to add backend logic |
| `server/googleSheetsService.ts` | Read/write orders, send emails, mark shipped |
| `server/googleSheetsUtil.ts` | Low-level Google Sheets row insertion for new orders |
| `server/uspsService.ts` | USPS address validation (OAuth2 token cached) |
| `server/pushNotifications.ts` | In-memory VAPID push subscription store |
| `client/src/pages/order-form.tsx` | The main customer-facing order experience |
| `client/src/components/NumberPadV2.tsx` | Touch numpad + product selection modal |
| `client/src/pages/order-management.tsx` | Admin dashboard (auth-free, protect by network) |
| `data/orderCounters.json` | Must persist — holds per-event order counters |
## State and Storage
### Backend
* Orders → Google Sheets (columns A-R)
* Order counters → `data/orderCounters.json`
* Push subscriptions → In-memory (lost on restart; admin must re-subscribe)
* Events cache → In-memory with 5 min TTL
### Frontend
* Form data → `localStorage` (auto-saved, cleared on submit)
* Image cache → React state (`Map`)
## Pricing Logic
Do not change pricing without updating all of these:
* `client/src/components/NumberPadV2.tsx` — `SIZES` array
* `client/src/pages/order-form.tsx` — `calculateItemTotal`, `calculate4x6Discount`, `PHOTO_SIZES`
* The "3 for $20" 4x6 discount: every 3 × 4x6 prints saves $4
## Adding a New API Endpoint
1. Add the route handler in `server/routes.ts` inside `registerRoutes()`
2. Use `googleSheetsOrderService` for any order reads/writes
3. Validate input with Zod
4. Call from the frontend with `apiRequest` from `@/lib/queryClient`
## Common Pitfalls
* `useToast` is at `@/hooks/use-toast` (not from shadcn directly)
* Image preview requires photo number ≥ 4 digits and a valid event slug (not `"CPS"`)
* USPS address validation requires `state` to be exactly 2 uppercase letters
* The admin manifest is at `/admin-manifest.webmanifest` — different from the customer PWA manifest
* `@shared/schema` resolves via tsconfig path alias — do not use relative `../../shared/schema`
## Recent additions & gotchas
* **dotenv must be imported** at the top of `server/index.ts` (or any entry) so `.env` values are available in dev. Missing it causes mysterious undefined credentials.
* The Replit runtime-error-modal plugin in `vite.config.ts` caused recurring "Pre-transform error: Failed to parse JSON file" logs and broken HMR when running locally. It's now only loaded when `REPL_ID` is defined.
* HMR configuration in `server/vite.ts` must specify `clientPort` (set to 5000) or the injected WS URL ends up `ws://localhost:undefined`, preventing hot reload.
* `/api/albums` needs to be a wrapper around `/event` (PHP backend) since the backend has no real albums endpoint; the server maps event objects to the album shape consumed by both frontend and `googleSheetsService`.
***