architecture-awareness

name	architecture-awareness
description	Architecture context before implementing — rendering model, service boundaries, layer depth.

Architecture Awareness

Routing Gate

Read only the section that matches your context. Loading this skill does not mean reading all of it.

Consumer / context	Read
Agent implementing server-side code	Backend Context
Agent implementing browser UI	Client Rendering Model + Frontend Context
Agent implementing native or cross-platform mobile UI	Mobile Context
Work crosses layers (full-stack task)	Both matching sections

Always applies, regardless of section: Layer Depth Contract (bottom of this file).

---

Client Rendering Model

Detect the model before touching a view. It determines where state and routing live, not which library is used.

Structural signal	Model	Consequence
A build step emits a JS bundle; server returns a shell HTML document; routes resolve client-side	Decoupled client	State, routing, and data fetching are client concerns; the server is a data API
Server returns fully-formed HTML per route; template files live beside controllers	Server-rendered templates	Routing, data, and views are one unit; JS enhances an already-working page
Server returns HTML for the first paint, then a client bundle takes over routing	Hybrid / server-side rendering with hydration	Every piece of code must declare which side it runs on; never assume browser globals exist

If the signals conflict (both a bundle config and server-side templates), the project is hybrid or migrating — ask before choosing a side.

---

Frontend Context

Decoupled client — the shipped bundle is a deliverable with a budget:

• Split code along route boundaries so an entry point loads only what its first screen needs
• Keep imports specific enough that unused exports can be dropped by the bundler (aggregating re-export modules defeat this)
• Serve images in a modern compressed format and size them to their rendered dimensions
• Measure before optimizing: run whatever bundle-analysis tool the project's bundler already provides (for example vite-bundle-visualizer or webpack-bundle-analyzer) rather than guessing at bloat
• Keep development and production build configuration explicitly separated — never ship development-only diagnostics

Server-rendered templates — the deliverable is HTML:

• Semantic markup first; the page must work before any script runs
• Render partials server-side rather than reconstructing them in JS
• Keep the JS footprint proportional to the enhancement it provides
• Coordinate with the backend-developer: routing, data, and views are handled together

Hybrid — for each module, state explicitly whether it runs on the server, the client, or both, and never reach for browser or server-only globals outside their side.

---

Backend Context

Structural signal	Model	Consequence
Views are rendered by a separate client; the server returns serialized data only	API-first (decoupled)	Focus on request/response contracts, validation, serialization, statelessness
Views are rendered by the same application that owns the routes and data	Monolithic (server-rendered)	Routing, controllers, and views change together
Multiple independently deployed services own separate data stores	Distributed services	Cross-service calls are network calls: define the contract, the timeout, and the failure behavior before writing them

• In a monolith the backend/frontend boundary is thin — coordinate with frontend-developer or ui-ux-designer when work touches views.
• In distributed services, never read another service's data store directly; go through its published contract.

---

Mobile Context

Bundle analysis and DOM-oriented rendering rules above do not apply. What matters:

Concern	Rule
Client/server boundary	The app is an untrusted client — every authorization decision is made server-side, never in the app
Offline and connectivity	Decide, per screen, what happens with no network: cached, queued, or blocked. Do not leave it implicit
API contract shape	Round trips are expensive on mobile networks — prefer contracts that fill a screen in one call over chatty per-widget endpoints
State ownership	Distinguish device-local state (survives relaunch) from server-owned state (must be reconciled on resume)
Native boundaries	Cross-platform code calling into native modules is a layer boundary — keep the platform-specific part isolated behind one interface

Platform UI conventions live in the platform skills, not here.

---

Layer Depth Contract

Before deciding on class structure, check architecture.md for the layer depth defined for the module being implemented — the software-architect may have specified different depths per domain area (a shallower chain for simple CRUD modules, a full chain including a persistence-abstraction layer for complex ones). Follow what is documented; do not infer a depth from other modules.