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.

Zypher team collaborating in a discovery session

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.

Response SLA: All Slack messages acknowledged within 4 working hours. Blockers escalated within 1 hour.

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.

Full source code transferGit history preservedInfrastructure credentials handed overRunbook & deployment guide included30-day post-handoff support windowOptional long-term retainer available

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.

mainProduction-deployable at all times
feat/short-nameFeature work — max 3 days lifetime
fix/issue-refBug fixes — branch from main, PR back fast
release/v2.1.0Release prep — frozen scope, hotfixes only

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.

1Push to mainTriggers GitHub Actions pipeline
2Lint + testESLint, TypeScript, Jest — all must pass
3Build & containeriseDocker image built, tagged with commit SHA
4Deploy to stagingAuto-deployed in <3 min. Smoke tests run
5Manual approval gateProduct sign-off required for production push
6Production deploymentBlue/green rollout with instant rollback

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.

Next.js App RouterReact Server ComponentsTailwind CSSFramer MotionZustand / JotaiReact QueryStorybookPlaywrightVitest

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.

PostgreSQLPrisma ORMRedis (cache/queues)Versioned migrationsSoft deletesRow-level securityRead replicas on scaleConnection pooling (PgBouncer)

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.

Apache KafkaCelery + RedisPrefect / Airflowdbt (transformations)Snowflake / BigQueryIdempotent consumersDead-letter queuesSchema Registry

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.

HashiCorp VaultAWS Secrets ManagerGitHub Actions secretsdotenv-vault (local dev)Secret rotation policyZero hardcoded credentialsAudit log on secret access

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.