Handbook
The PURISTA
handbook.
Start with the 15-minute tutorial, then go as deep as you need — from core mental models to enterprise patterns and live operations. Every chapter has builder-pattern examples in real TypeScript.
# install the PURISTA AI skill
npx skills add puristajs/purista --skill purista
# scaffold a new project
npm create purista@latest my-app
# add a service and its first command
purista add service user
purista add command signup
# run in development
npm run dev// user/v1/command/signup
export const signUpCommand = userV1ServiceBuilder
.getCommandBuilder('signUp', 'Register a user')
.addPayloadSchema(z.object({
email: z.string().email(),
name: z.string(),
}))
.setCommandFunction(async function (context, payload) {
const userId = await context.resources.db
.createUser(payload)
await context.emit('user.registered', { userId })
return { userId }
})Structured hands-on learning journeys — start here
Why PURISTA exists — the fundamental principles and mental models
Philosophy
The core philosophy and idea behind PURISTA
Separation of Concerns
Definition, implementation, and configuration are separate layers
Architecture
The nervous system connecting services without coupling
Data Control
Handling of confidential data and privacy controls
Distribution
Distribution implementation and runtime level
Resilience Through Patterns
Fault tolerance, retry logic, and graceful failure handling
Deployment Flexibility
Same code in monolith, microservices, serverless, edge
Understand what a Service is — the fundamental unit of organization
What is a Service?
Services are logical containers organizing related business logic
The Service Builder
Define metadata, attach handlers, and create instances
Service Configuration
Add typed custom configuration with Zod schemas
Resources & Dependencies
Database connections, APIs, external systems needed
Custom Service Class
Extend the base class for gateway and adapter patterns
Testing a Service
Validate setup, configuration, and wiring with unit tests
The patterns you'll use inside a service — high-level concepts, not detailed how-to guides
Command
Synchronous request/response handlers with typed schemas and validation
Stream
Transform continuous data pipelines in real-time
Subscription
Asynchronously react to business events
Queue & Worker
Reliable background work with automatic retry
AI Agent
Autonomous intelligence making decisions and taking actions
Three kinds of storage for different purposes
Making your service accessible to the outside world
Infrastructure connecting distributed services
Proven patterns for production systems
Schedule → Event → Queue → Result
Core enterprise pattern: scheduler triggers, event emitted, queue processes, result published
Scheduling
External orchestration of when work happens
Long-Running Workflows
Coordinating work across multiple async stages
AI Agent Patterns
Building systems with autonomous AI agents
Event Sourcing
Using events as the source of truth
CQRS
Separating reads and writes for scalability
Temporal Orchestration
Complex workflow orchestration with Temporal
See, debug, and optimize production systems
Observability
Logs, traces, metrics — understand what's happening
OpenTelemetry Backends
Connect PURISTA traces and metrics to your preferred observability platform
Deployment Architectures
Monolith, microservices, Kubernetes, edge, serverless
Reliability
Error handling, retries, circuit breakers, failure modes
Performance
Measurement, bottlenecks, optimization strategies
Security
Secrets, authentication, encryption, access control