Common Workflows

Step-by-step guides for recurring development tasks. Each workflow is designed to be followed sequentially.

Adding a New App

New App Checklist

Step	Action
1. Copy template	`cp -r apps/private/template-private apps/private/my-app`
2. Update package.json	Change `name` to `@frequencyads/my-app`
3. Update layout.tsx	Change metadata (title, description)
4. Update navbar.tsx	Change branding text
5. Create .env.local	Copy from an existing app
6. Install	`pnpm install` from monorepo root
7. Verify locally	`pnpm dev --filter=@frequencyads/my-app`
8. Create Vercel project	`cd apps/private/my-app && vercel link --yes`
9. Add domain	`vercel domains add my-app.yourdomain.com`
10. Configure DNS	Add CNAME for subdomain in Route 53
11. Set env vars	`vercel env add NEXT_PUBLIC_SUPABASE_URL` etc.
12. Deploy	`vercel --prod`

Deploying to Vercel

Deployment Checklist

Each app is its own Vercel project. See Deployment for architecture.

Step	Action
1. Link Vercel	`cd apps/private/my-app && vercel link --yes`
2. Add domain	`vercel domains add my-app.yourdomain.com`
3. DNS — subdomain	Route 53: CNAME `my-app` → `cname.vercel-dns.com`
4. GitHub secrets	`VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`, `VERCEL_TOKEN`
5. Env vars	`vercel env add <VAR_NAME>` for each variable
6. Deploy	`vercel --prod`
7. Verify	Check domain resolves, app loads, auth works

Adding a Schema Entity

Schema Development Workflow

1. Define in LinkML

Add your entity to packages/models/schemas/core.yaml (or create a new schema file):


classes:
  Invoice:
    description: Customer invoice
    attributes:
      id:
        range: string
        identifier: true
      amount:
        range: float
        required: true
      customer_id:
        range: UserProfile
      status:
        range: InvoiceStatus
 
enums:
  InvoiceStatus:
    permissible_values:
      draft: {}
      sent: {}
      paid: {}
      overdue: {}

2. Generate TypeScript Types


cd packages/models
node scripts/generate-types.mjs

3. Generate SQL Migration


node scripts/generate-migration.mjs

4. Apply Migration


# Apply to local Supabase
supabase migration up
 
# Or create a new migration file
supabase migration new add_invoices

5. Add RLS Policies

Manually review and add row-level security policies to the generated SQL:


ALTER TABLE invoices ENABLE ROW LEVEL SECURITY;
CREATE POLICY "Users can view their org invoices"
  ON invoices FOR SELECT USING (
    org_id IN (SELECT org_id FROM memberships WHERE user_id = auth.uid())
  );

6. Use in Application Code


import type { Invoice } from '@frequencyads/models';

Creating a Workspace Package

New Package Workflow

1. Create Package Directory


mkdir -p packages/my-package/src

2. Create package.json


{
  "name": "@frequencyads/my-package",
  "version": "0.0.0",
  "private": true,
  "exports": {
    ".": "./src/index.ts"
  },
  "dependencies": {},
  "devDependencies": {
    "@frequencyads/tsconfig": "^0.1.0",
    "typescript": "^5"
  }
}

3. Create tsconfig.json


{
  "extends": "@frequencyads/tsconfig/base.json",
  "compilerOptions": {
    "outDir": "dist"
  },
  "include": ["src"]
}

4. Add to Consumer Apps


{
  "dependencies": {
    "@frequencyads/my-package": "workspace:*"
  }
}

5. Install & Verify


pnpm install
pnpm type-check

Updating AI Drivers Submodule

AI Drivers Update


# Pull latest AI Drivers
cd .ai-drivers
git pull origin main
cd ..
 
# Commit the submodule update
git add .ai-drivers
git commit -m "Update AI Drivers submodule"

Environment Variable Sync

When adding a new environment variable:

Add it to .env.example with a placeholder value
Add it to every app’s .env.local with the real value
Add it to each Vercel project: vercel env add VAR_NAME
Document it in the Security page under Environment Variables

Remember: All apps share the same Supabase credentials. .env.local files should be identical unless there’s a specific reason to differ (e.g., VERCEL_URL).