Applications on Build Me Web — customer portals, booking tools, and internal systems — stay maintainable when you separate layers, design deliberate APIs, respect environments, and treat security as a default. This guide recommends patterns we use on client engagements.
Layers
Separate presentation, domain logic, and integrations. Keep business rules out of UI components so the same logic serves web and API clients. Presentation renders state and collects intent; domain services enforce invariants; adapters talk to payment providers, CRMs, and email.
Resist “god controllers” that validate input, charge cards, send email, and render HTML in one function. When a rule changes, you want one place to edit.
- Define bounded contexts (billing, identity, content) even in smaller apps.
- Put authorization checks at the domain edge, not only in the UI.
- Keep third-party SDKs behind adapters so vendor swaps do not rewrite the product.
- Prefer explicit DTOs over leaking database rows to clients.
Browser / mobile
↓
API gateway (authn/authz)
↓
Domain services
↓
Data stores & external APIsIf a screen needs five unrelated API calls to render, consider a server-side aggregate endpoint for that use case — carefully versioned — instead of chatty clients.
Data & APIs
Prefer versioned REST endpoints for external consumers (/v1/...). Use server-side sessions or tokens for authenticated routes. Avoid exposing admin capabilities on public clients — separate admin apps or tightly scoped tokens.
Pagination, filtering, and error shapes should be consistent. Idempotency keys belong on payment and order creation. Rate-limit aggressively on authentication and write endpoints.
- Read models can denormalize for UI speed; write models stay normalized enough for integrity.
- Migrations expand-contract: add columns, dual-write if needed, then remove old paths.
- Search and reporting often deserve read replicas or warehouses — do not overload the primary OLTP database with heavy dashboards.
Document public endpoints in the same spirit as our REST API reference: auth, resources, and error codes.
Environments
Dev, preview, and production should share config shape with different secrets. Seed preview with anonymized data that exercises real workflows — empty databases hide permission bugs.
Feature flags let you dark-launch. Keep flag cleanup on the backlog so the codebase does not become a graveyard of permanent “temporary” switches.
- Config keys identical across environments
- Secrets only in the vault
- Preview is noindex and uses sandbox providers
- Prod promotions require checks (and approvals on Managed)
Security basics
Enforce least privilege, validate all inputs, and log auth failures. Escape output in HTML contexts; parameterize queries. Review the Security page for org-wide controls available on Enterprise (SSO, audit exports, hardened networking).
Sessions: short-lived access tokens, rotating refresh tokens, Secure/HttpOnly/SameSite cookies where applicable. CSRF protections on cookie-based mutating requests.
Dependencies: pin versions, scan for known issues, and avoid installing packages you do not need. Secrets scanning in CI catches accidents early.
Best practices
Design for operability: structured logs, request IDs, and health checks that mean something. Load-test critical write paths before campaigns. Prefer boring technology for the money path. Revisit architecture when a new channel (mobile, partner API) appears — do not bolt it onto the UI layer.
Related reading: Authentication & accounts for identity detail, Internal tools for operator UX, and the REST API reference for platform APIs you may integrate with.
Prerequisites & preparation
Before changing production settings for application architecture, align the people who own content, DNS, analytics, and approvals. A fifteen-minute kickoff that names owners prevents multi-day Slack archaeology later. Capture decisions in the workspace notes so the next teammate inherits context instead of guesswork.
Gather credentials and access: workspace admin or editor role, DNS control when hostnames are involved, payment or API sandbox accounts when money paths are involved, and a shared checklist link. Confirm which environment you will rehearse in — preview first, production only after a green run.
Sketch bounded contexts, list external integrations, and agree environment parity requirements.
Detailed walkthrough
Work the happy path slowly the first time. Narrate what you expect to see after each click: a status badge, a DNS record, a webhook delivery, a Lighthouse metric. When reality diverges, stop and resolve the mismatch instead of clicking ahead — most outages begin as ignored yellow states.
- Separate presentation, domain, and adapter layers in the repo structure.
- Version public APIs; keep admin capabilities off public clients.
- Unify config keys across environments with vault-backed secrets.
- Add request IDs, structured logs, and meaningful health checks.
- Load-test the primary write path before campaigns.
Edge cases & failure modes
Plan for partial failure. Networks drop, registrars delay, providers rate-limit, and humans approve the wrong revision. Your runbook should say what “abort” looks like: leave preview up, roll back the release, or freeze campaigns until metrics recover.
- Config key drift between preview and production.
- Health checks that only hit static HTML.
- Migrations incompatible with blue-green overlap.
QA checklist before you announce
- Happy path verified on mobile and desktop
- Failure path messaging reviewed
- Owners named for the first hour after launch
- Rollback or freeze path documented
Operating the change
After launch, watch the metrics that prove the change worked — not vanity charts. Pair quantitative signals with one qualitative check (support ticket themes, sales feedback). Schedule a follow-up within a week to remove temporary flags, raise DNS TTLs, or archive the experiment.
Review feature flag debt monthly; delete flags that shipped permanently.
Treat application architecture as a repeatable playbook. The second time your team runs it should be faster because the checklist and owners already exist.
Authorization belongs on the server for every mutate — hidden UI buttons are not security.
Expand/contract migrations keep blue-green deploys from breaking old instances mid-shift.
Read replicas or warehouses should absorb heavy reporting so OLTP stays responsive.
Adapters around vendor SDKs make payment or email provider swaps survivable.
Prefer boring technology on the money path; experiment at the edges.
When a new channel arrives (mobile, partners), extend the domain layer — do not bolt logic onto UI widgets.
Document public error shapes so clients handle 429 and 409 coherently.
Implementation checklist
Confirm bounded context boundaries in the repo on preview before you promote. Name who approves the change, which environment is authoritative, and what “done” looks like in measurable terms.
Document server-side authorization on every mutate where the team already looks — workspace notes or the engineering handbook — not only in a meeting memory.
Rehearse versioned external API contracts against written acceptance checks. If you cannot name the verification event (order, DNS lookup, deploy health, or signed API call), you are not ready to announce.
Measure expand-contract migration strategy with anonymized but realistic data, and keep logs, headers, or screenshots for at least one release cycle so regressions have a baseline.
Operating it with your team
Automate structured logging with request IDs so the next teammate can repeat the path without tribal knowledge. Prefer vaulted secrets over chat paste, and archive temporary exceptions with an end date.
Review feature flag cleanup debt reviews when two tools disagree. Pick a source of truth in advance so incidents do not burn the rollback window debating dashboards.
Validate read replica usage for heavy reports before paid traffic or customer emails amplify mistakes. Capture request IDs or screenshots for support if anything looks off.
Schedule a follow-up on adapter layers around vendor SDKs after launch, update the runbook when reality differs from the doc, and assign a named owner for the first hour.
When you finish this guide, you should be able to explain the happy path, the abort path, and the metrics that prove success. If any of those are fuzzy, revisit the walkthrough with your teammates before you scale traffic, spend, or automation.