Documentation
How we build
Engineering standards, process guides, and architectural patterns used across every Zypher engagement.
How We Engage
Every Zypher project begins with a free discovery call. We listen first — understanding your business goals, technical constraints, and user needs before suggesting any solution. After discovery, we produce a written specification that becomes the shared contract for delivery.
We operate in two-week sprints with a demo at the end of every cycle. You review, give feedback, and we adjust. There are no hidden surprises at handoff because you see the product being built in real time.

A typical Zypher discovery session — we listen before we build.
Project Kickoff
The kickoff call happens within 48 hours of contract signing. It covers team introductions, tooling setup, communication channels, and a walkthrough of the agreed specification. By the end of week one, your codebase exists, CI is running, and the team is shipping.
Day 1 — Onboarding
Repo access, environment setup, Slack channel created, Notion workspace shared.
Day 2 — Spec review
Technical spec walkthrough with all stakeholders. Questions answered, scope locked.
Day 3–5 — Scaffolding
Project scaffolded, CI/CD wired, linting and test runner configured.
Week 2 — First sprint
First feature slice shipped to staging. Demo scheduled for end of sprint.
Communication Norms
We believe great software is built on great communication. Here's what every Zypher engagement looks like from a communication perspective:
Async-first
Loom videos and written updates over surprise meetings.
Weekly standups
One 30-min call per week — never longer, always recorded.
Shared Notion
Every spec, decision, and design lives in one place.
Slack channel
Direct access to your Zypher engineer team, no ticketing system.
Handoff & Ownership
Full IP and codebase ownership transfers to you on final delivery. We don't retain any rights to the code, designs, or documentation produced during your engagement.
Every project ends with a handoff session — we walk your team through the architecture, deployment process, and known gotchas. We also produce a written runbook so any engineer can take over confidently.
Code Review Policy
No code merges to main without a peer review. Every pull request must have at least one approval from a Zypher engineer who wasn't the author, with automated checks passing first.
PR size limit
PRs capped at ~400 lines of net-new code to keep reviews fast and focused.
Tests required
New features must include unit tests. CI fails on coverage regression.
Security scan
Automated SAST on every PR via CodeQL. Critical findings block merge.
Squash & merge
Clean commit history on main. Feature branches squashed before merge.
Git Branching Strategy
We follow a trunk-based development model with short-lived feature branches. main is always deployable.
Testing Requirements
We bake testing into the development cycle — not bolted on at the end. Every service has unit, integration, and a subset of end-to-end tests before it ships to staging.
Unit tests
Functions and components tested in isolation. Jest / Vitest. Minimum 80% coverage on business logic.
Integration
API routes, database queries, and service boundaries tested against a real test database.
E2E tests
Critical user journeys (auth, checkout, onboarding) tested with Playwright before every release.
Deployment Workflow
Deployments are automated, gated, and reversible. Every push to main triggers a pipeline that promotes code through environments only after all checks pass.
Frontend Architecture
We default to Next.js App Router with React Server Components for web projects, and Flutter for cross-platform mobile. All UIs are built against a component library generated alongside the design system.
Backend & API Design
REST by default, GraphQL when the client demands it. Every API is versioned, rate-limited, and returns standardised error shapes so frontend teams never have to guess.
Versioned endpoints
All APIs are prefixed with /v1/. Breaking changes bump the version, not the existing clients.
Standard error shape
{ code, message, details } on every error — no undocumented error formats.
Rate limiting
Every public endpoint has rate limits configured. Limits surfaced in response headers.
OpenAPI spec
Auto-generated from code. Clients get a type-safe SDK on request.
Database Conventions
PostgreSQL is our default. We use Prisma as an ORM for type safety, with raw SQL for complex queries. All schema changes go through versioned migrations — never direct schema edits in production.
Cloud & Infrastructure
All infrastructure is defined as code (Terraform), version-controlled, and reproducible across environments. We avoid console-clicking infrastructure at all costs.
IaC with Terraform
Every resource defined, version-controlled, and reviewable as a PR.
Multi-environment
dev → staging → production. No exceptions. Each environment isolated.
Observability stack
Prometheus + Grafana. Distributed tracing via OpenTelemetry.
Cost governance
Monthly cost reports, resource tagging, and budget alerts configured on every account.
LLM Integration Patterns
We integrate LLMs as structured services with retries, fallbacks, and cost caps — not fire-and-forget API calls. Every prompt is versioned and monitored.
Prompt versioning
Prompts stored in code alongside the model version they target. A/B tested before rollout.
Streaming responses
All chat interfaces use streaming for perceived speed. UI handles partial states gracefully.
Cost caps
Per-user and per-request token budgets enforced server-side. Never exposed to the client.
Eval harnesses
Golden dataset of expected outputs tested on every model or prompt upgrade.
Data Pipeline Setup
Data pipelines are built for reliability first. Every pipeline has a dead-letter queue, alerting on failure, and idempotent processing so re-runs never duplicate data.
Model Evaluation
Before shipping any model change to production, we run a structured evaluation against a golden dataset. Regressions in accuracy, latency, or cost block the release.
Golden dataset
Curated input/output pairs covering edge cases. Managed as a versioned artifact.
Latency budget
p95 latency threshold defined per use case. Violations fail CI.
Human-in-the-loop
Spot-check review queue for low-confidence outputs before they reach end users.
Regression reports
Side-by-side output comparisons generated automatically for every eval run.
OWASP Top 10
Every project goes through an OWASP Top 10 checklist before launch. Here's how we address the most common categories:
Injection
Parameterised queries only. No raw user input in SQL or shell commands.
Broken Authentication
Short-lived JWTs, refresh token rotation, and MFA enforced on admin routes.
Sensitive Data Exposure
PII encrypted at rest and in transit. Minimal data collection by default.
Security Misconfiguration
Hardened default configs, no debug endpoints in production, headers audited.
Cross-Site Scripting (XSS)
Sanitised DOM output, CSP headers, no dangerouslySetInnerHTML without review.
Auth & Session Management
We use proven auth providers (Auth.js, Clerk, Supabase Auth) rather than custom implementations. Session tokens are short-lived, rotated on use, and invalidated server-side on logout.
JWT + refresh rotation
Access tokens valid for 15 min. Refresh tokens rotated on every use and stored httpOnly.
MFA on admin routes
TOTP or WebAuthn required for any admin or elevated-privilege action.
No sensitive data in JWT
Tokens contain only user ID and role. PII never serialised into the token payload.
Brute-force protection
Account lockout after 5 failed attempts. Rate limiting on all auth endpoints.
Secrets Management
No secrets in source control — ever. All credentials are injected at runtime via environment variables, secret managers, or Vault, depending on the project's compliance requirements.
Penetration Testing
We conduct penetration testing before every major release and on an annual schedule for long-running products. Tests are performed by a third-party firm — not the build team.
Scope
All public-facing endpoints, authenticated routes, and file upload surfaces.
Methodology
OWASP WSTG + PTES. Black-box and grey-box depending on engagement type.
Report delivery
Full report with CVSS scores, reproduction steps, and remediation guidance within 5 days.
Re-test included
All critical and high findings are re-tested at no additional cost after remediation.