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.