Widgetsflow
Services Portfolio Process About Blog Contact
Book Now
Services Portfolio Process About Blog Contact
Book Now
Engineering Standards

Our Standards

We don't just ship apps — we build them right. Every variable named, every endpoint versioned, every input validated. Here's how.

100%
Type-safe codebases
/v1+
Versioned APIs from day one
Zero
Secrets committed to git
01

Naming Conventions

Consistent naming is the foundation of a readable codebase. Every developer should open a file and immediately understand intent — no guessing.

camelCaseVariables & Functions

Local variables, state values, and event handler functions — the universal JS/TS convention.

getUserProfile · handleSubmit · isLoading · onAuthChange
PascalCaseClasses, Components & Types

Every class, React component, TypeScript interface, and Dart widget — visually distinct from function calls.

AuthService · UserProfileCard · ApiResponse<T>
SCREAMING_SNAKEConstants & Config

Module-level constants and env-driven config — signals immutability at a glance, never reassigned.

MAX_RETRY_ATTEMPTS · API_BASE_URL · TOKEN_TTL
snake_caseDatabase Fields

Database columns and server JSON keys — matches PostgreSQL defaults, no case ambiguity.

user_id · created_at · is_verified · refresh_token
kebab-caseAPI Routes & URL Slugs

HTTP endpoint paths and URL slugs — lowercase, URL-safe, readable without decoding.

/api/v1/user-profiles/:id · /auth/refresh-token
naming-conventions.ts
// Variables & functions ─────────────── camelCase
const userProfile = await getAuthenticatedUser(userId);
const isSubscribed = checkSubscription(user.id);
const handleSubmit = (e: FormEvent) => {};
 
// Classes & Components ──────────────── PascalCase
class AuthService { /* manages all auth flows */ }
function UserProfileCard({ user }: Props) { ... }
interface ApiResponse<T> { data: T; ok: boolean }
 
// Constants ─────────────── SCREAMING_SNAKE_CASE
const MAX_RETRY_ATTEMPTS = 3;
const API_BASE_URL = process.env.NEXT_PUBLIC_API_URL;
const TOKEN_EXPIRY_MS = 15 * 60 * 1000; // 15 min
 
// DB fields → snake_case | Routes → kebab-case
// { user_id, created_at, is_verified, refresh_token }
// GET /api/v1/user-profiles/:id
// POST /api/v1/auth/refresh-token
02

API Design Standards

Every API ships with consistent response envelopes, versioned routes, and predictable error payloads — so integrations never surprise you.

routes/index.ts
// All routes versioned at /api/v1/
 
// ── Users
GET /api/v1/users → list + paginate
GET /api/v1/users/:id → single record
POST /api/v1/users → create + return
PUT /api/v1/users/:id → full replace
PATCH /api/v1/users/:id → partial update
DELETE /api/v1/users/:id → soft-delete
 
// ── Auth
POST /api/v1/auth/login
POST /api/v1/auth/logout
POST /api/v1/auth/refresh-token
POST /api/v1/auth/forgot-password
 
// Breaking changes → bump to /api/v2/
// v1 alive for 6-month deprecation window.
api-envelope.json
// ✓ Success
{
"success": true,
"data": { "id": "usr_01HX9F...", "role": "editor" },
"meta": { "timestamp": "2026-06-21T12:00:00Z" }
}
 
// ✗ Error — structured, never a plain string
{
"success": false,
"error": {
"code": "TOKEN_EXPIRED",
"message": "Access token has expired.",
"docs": "/docs/errors#TOKEN_EXPIRED"
}
}
Rules We Always Follow
Versioned from day one
/api/v1/ from the first commit. Breaking changes bump the major — never silently break clients.
Consistent response envelope
Every response carries success, data, and meta. Clients never guess the shape of the payload.
Structured errors, always
Errors include a machine code, human message, and docs link. Never a raw 500 string.
Idempotent by design
PUT replaces; PATCH changes only what's sent. Repeated calls produce identical results.
Paginated collections
All list endpoints support cursor or offset pagination. No unbounded queries in production.
03

Code Architecture

A clear folder structure and solid design principles keep the codebase maintainable as it scales — from 1 developer to a full team.

project/
project/
├── src/
│ ├── api/ ← route handlers ONLY
│ │ └── v1/
│ │ ├── users.ts
│ │ └── auth.ts
│ ├── services/ ← all business logic
│ │ ├── userService.ts
│ │ └── authService.ts
│ ├── models/ ← Zod schemas + DB types
│ ├── middleware/ ← auth · rate-limit · validate
│ ├── utils/ ← pure, side-effect-free
│ └── config/ ← env vars + constants only
├── tests/
│ ├── unit/
│ └── integration/
└── .env.example ← committed; .env is ALWAYS gitignored
Separation of Concerns

Routes handle HTTP. Services handle logic. Models handle data. No layer reaches into another's domain.

Single Responsibility

Each function or class does exactly one thing. The name tells you what — no extra documentation needed.

DRY Codebase

Shared logic lives in utils/ or services/. Copy-paste is a code smell we fix before a PR is merged.

Conventional Commits

feat:, fix:, chore:, refactor:, docs: — every commit. The git log is a changelog, not a mystery.

04

Security First

Security isn't a feature we add after launch. Every project ships with these rules applied from day one — no exceptions.

security.ts
// 1. Input validation — Zod on every endpoint
const CreateUserSchema = z.object({
email: z.string().email(),
password: z.string().min(10).regex(/[A-Z0-9!@#]/),
role: z.enum(['admin', 'viewer', 'editor']),
});
 
// 2. Short-lived JWTs + rotating refresh tokens
const access = jwt.sign(payload, SECRET, { expiresIn: '15m' });
const refresh = jwt.sign({ id }, REFRESH, { expiresIn: '7d' });
 
// 3. Rate limiting — 100 req / 15 min per IP
app.use(rateLimit({ windowMs: 900_000, max: 100 }));
 
// 4. CORS — explicit allowlist, never wildcard *
app.use(cors({ origin: ['https://widgetsflow.com'] }));
 
// 5. HTTPS + HSTS headers on all production responses
// 6. GitHub secret scanning enabled on every push
Non-Negotiable Rules
Input Validation
Zod schemas validate every incoming request. Malformed payloads are rejected at the boundary before touching any logic.
JWT with Rotation
Access tokens expire in 15 min. Refresh tokens rotate on every use — leaked tokens expire fast.
Rate Limiting
100 req/15 min on all public endpoints. Auth routes capped at 5/min to deter brute-force attacks.
HTTPS + HSTS
All production traffic is HTTPS-only with HSTS headers. HTTP requests are redirected; certs auto-renew.
Secrets in .env Only
Zero credentials in source code. Env vars only, with GitHub secret scanning enabled on every push.
Strict CORS Policy
Explicit origin allowlist — no wildcard * in production. Unknown origins are blocked outright.
Work With Us

Built right from the start.

Every project we take on ships with these standards applied by default. No shortcuts, no exceptions.

Start your Project