CentercodePorygon
DittoPorygonAPI

Porygon

Backend Engineering Guide

Safe
Fast
Reliable

Welcome to Porygon

Pattern Library

Tested backend patterns for APIs, data access, and services - designed for enterprise user testing.

porygon-eng Skill

Claude Code agent skill with guardrails and patterns to build aligned with Porygon - preventing drift automatically.

Documentation Site

This /porygon/ site helps engineers understand capabilities and direct AI agents effectively.

Workflow: Workflow: Explore docs, then direct AI using pattern names. The skill ensures correct implementation.

Engineering Goals

Every Porygon topic maps to one or more engineering pillars:

Safe
Safe

Security-first development prevents vulnerabilities, protects user data, and ensures compliance.

Fast
Fast

Performance optimization minimizes latency, maximizes throughput, and scales efficiently.

Reliable
Reliable

Consistent behavior, predictable responses, and comprehensive error handling build trust.

Foundations

Core infrastructure patterns every backend feature depends on

API Architecture
REST patterns, versioning, and response envelopes
Error Handling
Typed error classes and consistent error responses
Validation
Zod schemas for runtime input validation
ESLint Rules
Build-time code quality and architecture enforcement
Logging
Structured logging with Pino
Prisma ORM
Type-safe database access with Prisma
Soft Delete
Recoverable deletion with cascade tracking

Services

External service integrations

AI Integration
Text and structured output generation with Vercel AI SDK
Background Jobs
Event-driven background processing with Inngest
File Storage
Secure file uploads with Vercel Blob
Email
Transactional email with Resend and React Email
Analytics
Product analytics and feature flags with PostHog
Image Processing
SVG to PNG conversion for email compatibility

Security

Authentication, authorization, and protection

Authentication
Session management with Better Auth
Authorization
Role-based and scope-based access control
Row-Level Security
Automatic data isolation at the database level
API Keys
Programmatic access authentication for external integrations
API Logging
Track and analyze API usage across the platform
Rate Limiting
Request throttling with Upstash Redis
Abuse Prevention
Bot detection and spam protection for public forms
Security Headers
HTTP security headers and CORS configuration

Architecture

System design and structure patterns

Feature Structure
Domain-driven feature module organization
Scope Model
User, program, and project scope isolation

Features

Domain-specific feature implementations

Universal Data Engine
Queryable data layer for filtering, enrichment, and tokens
Form System
Dynamic block-based form engine architecture
Block Definitions
Creating and registering form block types
Insights
AI-powered feedback processing and scoring
Translations
AI-powered content translation with inheritance
Gates
Blocking resources that users must complete before proceeding

Operations

Deployment, monitoring, and testing

Deployment
Vercel deployment and database migrations
Monitoring
Observability, health checks, and alerting
Data Flow
Server Components, Server Actions, and Route Handlers
Testing
API testing with curl and manual verification

Pattern Quick Reference

Request these patterns by name when directing AI agents.

API Patterns

Response Envelope ok/data object format

validateRequest() Zod body validation

handleError() Error response wrapper

Data Patterns

Repository Pattern Data access layer

prisma client Type-safe ORM

Transactions Atomic operations

Infrastructure

logger Structured logging

Error Classes Typed HTTP errors

Zod Schemas Runtime validation

When directing AI agents to build backend features: Ditto Design System

AI Direction Tips

When directing AI agents to build backend features:

  1. Reference pattern names: 'Use the response envelope pattern' or 'Follow the repository pattern'
  2. Specify pillars: 'Prioritize safety' or 'This needs to be fast'
  3. Link to examples: 'See /examples/api/example-route.ts for the pattern'
  4. Call out anti-patterns: 'Do NOT use console.log, use logger'
  5. Reference this site: 'See /porygon/validation for the validation patterns'