Back to Library
Safety

AI Agent Instructions

Updated 1/19/2026
1 min read

AI Agent Developer Guide

This document outlines the core principles and workflows for developers (and AI agents) contributing to Postcard.

Core Principle

Utilize Cloudflare's platform capabilities (Images, Stream, D1, R2) to their fullest. Prioritize the simplest approach that meets the requirements.

Infrastructure Reference

  • Account ID: 5f36343cbcbae0a78d45ae8bb825f8b3
  • Database: postcard-db
  • API Domain: api.getpostcard.app
  • Admin Domain: admin.getpostcard.app

Implementation Guidelines

1. Backend (Cloudflare Workers)

  • Direct Uploads: Never proxy media through Workers. Generate signed URLs for direct client-to-Cloudflare uploads.
  • SQL Safety: Always use D1 prepared statements (.bind()) to prevent injection.
  • Error Responses: Maintain a consistent JSON error format.
  • Pagination: Use cursor-based pagination for all feeds and lists.

2. iOS App (SwiftUI)

  • Design Fidelity: Follow mockups in /mockups/ exactly.
  • Minimalism: Maintain the black-and-white aesthetic.
  • Concurrency: Use Swift async/await for all networking and asynchronous tasks.
  • Auth: Manage sessions gracefully via Auth0 and Keychain.

Developer Workflow

Local Development

# Start local API dev server
npx wrangler dev

Database Migrations

# Create migration
npx wrangler d1 migrations create postcard-db [name]
# Apply locally
npx wrangler d1 migrations apply postcard-db --local

Deployment

# Deploy API
npm run deploy
# Deploy Admin Panel
npm run admin:deploy