name: modern-web-app-architecture
description: Use when designing or building modern web applications in JavaScript/TypeScript (SPA/SSR/SSG/ISR/RSC): architecture trade-offs, state/data patterns, performance, testing, delivery, and team scaling.
Modern Web App Architecture (SPA/SSR/SSG/RSC)
Overview
Comprehensive guidance for designing and building modern web applications (including SPAs and hybrid rendering apps). This skill emphasizes trade-offs, explicit boundaries, and production-ready practices (performance, accessibility, security, testing, delivery).
Core principle: Everything in architecture is a trade-off. There are no "right" answers, only least-worst combinations for your specific context.
Operating Mode (How to Use This Skill)
When activated, work in this order:
- Clarify context (5–10 questions max) → users, routes, SEO, interactivity, data, auth, team, constraints.
- Choose a rendering strategy per route (not “one strategy for the whole app”).
- Define boundaries → feature/domain modules, shared libraries, ownership, and stable interfaces.
- Plan state + data → local/shared/global/server/URL state, cache strategy, invalidation, optimistic updates.
- Plan non-functionals → performance budgets + measurement, accessibility plan, security posture, observability.
- Produce artifacts → short recommendations with explicit trade-offs, plus concrete next steps (folder structure, ADRs, checklists).
If the user can’t answer a question, state reasonable assumptions and continue (don’t block).
When to Use
- Starting a new SPA or web application
- Choosing rendering strategies (CSR, SSR, SSG, ISR, RSC)
- Implementing state management
- Optimizing Core Web Vitals (LCP/INP/CLS)
- Scaling for multiple frontend teams
- Making architecture trade-off decisions
- Migrating from legacy to modern frontend
Quick Discovery Questions (Ask First)
- What are the top 3 user journeys and their target latency (e.g., “search → product → checkout”)?
- Is SEO required for any routes? Which are public vs behind auth?
- What’s the data shape: mostly CRUD, real-time, offline-first, heavy forms, large tables/charts?
- What are the constraints: browser support, bundle limits, time-to-market, compliance (SOC2/HIPAA/PCI)?
- What’s the team topology: how many devs/teams, release cadence, ownership boundaries?
- What’s your preferred stack (React/Vue/Angular/vanilla), and are you open to TypeScript?
Reference Files
| Topic |
When to Load |
| @references/design-patterns.md |
Implementing JS patterns (Module, Observer, Factory, etc.) |
| @references/react-patterns.md |
React components, hooks, state, composition |
| @references/spa-fundamentals.md |
SPA architecture, routing, module organization |
| @references/micro-frontends.md |
Scaling teams, independent deployments |
| @references/performance.md |
Bundle size, loading, Core Web Vitals |
| @references/architecture-decisions.md |
Trade-offs, coupling, fitness functions |
| @references/rendering-strategies.md |
CSR vs SSR vs SSG vs ISR vs RSC |
| @references/state-management.md |
Local, global, server state patterns |
| @references/security-and-auth.md |
Auth choices, token storage, XSS/CSRF, CSP, API boundaries |
| @references/accessibility-and-i18n.md |
WCAG basics, SPA focus mgmt, inclusive components, i18n pitfalls |
| @references/testing-and-quality.md |
Testing strategy, CI quality gates, a11y checks, contract tests |
| @references/tooling-and-delivery.md |
Bundling, environments, deployment, observability, feature flags |
Quick Architecture Decision Tree
Project Requirements?
├─ SEO critical + dynamic content → SSR (or SSR+streaming)
├─ SEO critical + mostly static → SSG/ISR (or hybrid)
├─ Mostly behind auth + app-like UX → CSR SPA (or hybrid with pre-rendered shell)
├─ Mixed (marketing + app) → Hybrid/Islands (route-level strategy)
│
Team Size?
├─ <5 developers → Modular monolith SPA
├─ 5-15 developers → Well-structured SPA or Service-based
├─ >15 developers, multiple teams → Consider micro-frontends
│
Domain Complexity?
├─ Simple CRUD → Layered architecture
├─ Complex workflows → Domain-partitioned (DDD)
├─ Multiple bounded contexts → Micro-frontends
Default Outputs (What You Should Produce)
Depending on the user request, aim to output:
- Route strategy map: a small table of routes → CSR/SSR/SSG/ISR/RSC + why
- Module boundary sketch: feature folders, shared libs, interface contracts
- State map: local/shared/global/server/URL, plus the chosen tooling pattern
- Data plan: caching/invalidation, error states, optimistic updates, pagination
- Quality plan: testing layers + CI gates + accessibility checks
- Performance plan: budgets + measurement + concrete loading strategy (split points)
- Risk register: top 5 risks + mitigations (e.g., hydration cost, auth posture, team coupling)
Essential Patterns Quick Reference
Component Patterns
| Pattern |
Use When |
| Container/Presentational |
Separating data from UI |
| Compound Components |
Building composable APIs (Select, Menu) |
| Hooks |
Sharing stateful logic without HOCs |
| Provider |
Avoiding prop drilling for global data |
State Management
| Approach |
Use When |
| useState/useReducer |
Local component state |
| Context |
Theme, auth, low-frequency global state |
| Zustand/Jotai |
Simple global state, minimal boilerplate |
| Redux Toolkit |
Complex state, time-travel debugging |
| React Query/SWR |
Server state, caching, background refresh |
| XState |
Complex flows with explicit state machines |
Performance Essentials
| Technique |
Impact |
| Code splitting |
Reduce initial bundle |
| Lazy loading |
Defer non-critical |
| React.memo |
Prevent unnecessary re-renders |
| useMemo/useCallback |
Stable references |
| Virtual lists |
Handle large datasets |
Architecture Characteristics (Pick 3-7)
| Characteristic |
Questions to Ask |
| Scalability |
How many concurrent users? Growth rate? |
| Performance |
What's acceptable TTI? LCP target? |
| Deployability |
How often do you ship? Independent deploys? |
| Testability |
How easy to verify changes? |
| Maintainability |
What's the expected lifespan? |
| Modularity |
How often do requirements change? |
Anti-patterns to Avoid
| Anti-pattern |
Problem |
Fix |
| Prop drilling |
Tight coupling |
Context or state management |
| God components |
Too many responsibilities |
Split by concern |
| Premature optimization |
Complexity without evidence |
Profile first |
| Shared mutable state |
Race conditions, bugs |
Immutable patterns |
| Monolithic bundle |
Slow initial load |
Code splitting |
| Over-fetching |
Wasted bandwidth |
GraphQL or BFF |
| LocalStorage tokens by default |
XSS turns into account takeover |
Prefer httpOnly cookies + CSP (see security refs) |
| Global store for server data |
Cache invalidation pain |
Use React Query/SWR for server state |
Performance Budgets
Budgets must be calibrated to your users/devices, but these are good starting points for a “fast by default” app:
| Metric |
Target |
Needs Work |
| LCP |
<2.5s |
2.5–4s |
| INP |
<200ms |
200–500ms |
| CLS |
<0.1 |
0.1–0.25 |
| TTFB |
<800ms |
800ms–1.8s |
| Route JS (initial) |
<170KB gzip |
<300KB gzip |
Sources
Synthesized from:
- Learning JavaScript Design Patterns (Osmani, 2023)
- React in Depth (Barklund, 2024)
- SPA Design and Architecture (Scott)
- Single Page Web Applications (Mikowski & Powell)
- Building Micro-Frontends (Mezzalira)
- Micro Frontends in Action (Geers)
- Responsible JavaScript (Wagner)
- High Performance Browser Networking (Grigorik)
- Web Performance in Action (Wagner)
- Frontend Architecture for Design Systems (Godbolt)
- Fundamentals of Software Architecture (Richards & Ford)
- Software Architecture: The Hard Parts (Ford et al.)
- Patterns.dev
1---2name: modern-web-app-architecture3description: Use when designing or building modern web applications in JavaScript/TypeScript (SPA/SSR/SSG/ISR/RSC): architecture trade-offs, state/data patterns, performance, testing, delivery, and team scaling.4---5
6---
7name: modern-web-app-architecture
8description: Use when designing or building modern web applications in JavaScript/TypeScript (SPA/SSR/SSG/ISR/RSC): architecture trade-offs, state/data patterns, performance, testing, delivery, and team scaling.
9---
10
11# Modern Web App Architecture (SPA/SSR/SSG/RSC)
12
13## Overview
14
15Comprehensive guidance for designing and building modern web applications (including SPAs and hybrid rendering apps). This skill emphasizes trade-offs, explicit boundaries, and production-ready practices (performance, accessibility, security, testing, delivery).
16
17**Core principle:** Everything in architecture is a trade-off. There are no "right" answers, only least-worst combinations for your specific context.
18
19## Operating Mode (How to Use This Skill)
20
21When activated, work in this order:
22
231. **Clarify context (5–10 questions max)** → users, routes, SEO, interactivity, data, auth, team, constraints.
242. **Choose a rendering strategy per route** (not “one strategy for the whole app”).
253. **Define boundaries** → feature/domain modules, shared libraries, ownership, and stable interfaces.
264. **Plan state + data** → local/shared/global/server/URL state, cache strategy, invalidation, optimistic updates.
275. **Plan non-functionals** → performance budgets + measurement, accessibility plan, security posture, observability.
286. **Produce artifacts** → short recommendations with explicit trade-offs, plus concrete next steps (folder structure, ADRs, checklists).
29
30If the user can’t answer a question, state reasonable assumptions and continue (don’t block).
31
32## When to Use
33
34- Starting a new SPA or web application
35- Choosing rendering strategies (CSR, SSR, SSG, ISR, RSC)
36- Implementing state management
37- Optimizing Core Web Vitals (LCP/INP/CLS)
38- Scaling for multiple frontend teams
39- Making architecture trade-off decisions
40- Migrating from legacy to modern frontend
41
42## Quick Discovery Questions (Ask First)
43
44- What are the top 3 user journeys and their target latency (e.g., “search → product → checkout”)?
45- Is **SEO** required for any routes? Which are public vs behind auth?
46- What’s the **data shape**: mostly CRUD, real-time, offline-first, heavy forms, large tables/charts?
47- What are the constraints: **browser support**, bundle limits, time-to-market, compliance (SOC2/HIPAA/PCI)?
48- What’s the **team topology**: how many devs/teams, release cadence, ownership boundaries?
49- What’s your preferred stack (React/Vue/Angular/vanilla), and are you open to TypeScript?
50
51## Reference Files
52
53| Topic | When to Load |
54|-------|--------------|
55| @references/design-patterns.md | Implementing JS patterns (Module, Observer, Factory, etc.) |
56| @references/react-patterns.md | React components, hooks, state, composition |
57| @references/spa-fundamentals.md | SPA architecture, routing, module organization |
58| @references/micro-frontends.md | Scaling teams, independent deployments |
59| @references/performance.md | Bundle size, loading, Core Web Vitals |
60| @references/architecture-decisions.md | Trade-offs, coupling, fitness functions |
61| @references/rendering-strategies.md | CSR vs SSR vs SSG vs ISR vs RSC |
62| @references/state-management.md | Local, global, server state patterns |
63| @references/security-and-auth.md | Auth choices, token storage, XSS/CSRF, CSP, API boundaries |
64| @references/accessibility-and-i18n.md | WCAG basics, SPA focus mgmt, inclusive components, i18n pitfalls |
65| @references/testing-and-quality.md | Testing strategy, CI quality gates, a11y checks, contract tests |
66| @references/tooling-and-delivery.md | Bundling, environments, deployment, observability, feature flags |
67
68## Quick Architecture Decision Tree
69
70```
71Project Requirements?
72├─ SEO critical + dynamic content → SSR (or SSR+streaming)
73├─ SEO critical + mostly static → SSG/ISR (or hybrid)
74├─ Mostly behind auth + app-like UX → CSR SPA (or hybrid with pre-rendered shell)
75├─ Mixed (marketing + app) → Hybrid/Islands (route-level strategy)
76│
77Team Size?
78├─ <5 developers → Modular monolith SPA
79├─ 5-15 developers → Well-structured SPA or Service-based
80├─ >15 developers, multiple teams → Consider micro-frontends
81│
82Domain Complexity?
83├─ Simple CRUD → Layered architecture
84├─ Complex workflows → Domain-partitioned (DDD)
85├─ Multiple bounded contexts → Micro-frontends
86```
87
88## Default Outputs (What You Should Produce)
89
90Depending on the user request, aim to output:
91- **Route strategy map**: a small table of routes → CSR/SSR/SSG/ISR/RSC + why
92- **Module boundary sketch**: feature folders, shared libs, interface contracts
93- **State map**: local/shared/global/server/URL, plus the chosen tooling pattern
94- **Data plan**: caching/invalidation, error states, optimistic updates, pagination
95- **Quality plan**: testing layers + CI gates + accessibility checks
96- **Performance plan**: budgets + measurement + concrete loading strategy (split points)
97- **Risk register**: top 5 risks + mitigations (e.g., hydration cost, auth posture, team coupling)
98
99## Essential Patterns Quick Reference
100
101### Component Patterns
102| Pattern | Use When |
103|---------|----------|
104| Container/Presentational | Separating data from UI |
105| Compound Components | Building composable APIs (Select, Menu) |
106| Hooks | Sharing stateful logic without HOCs |
107| Provider | Avoiding prop drilling for global data |
108
109### State Management
110| Approach | Use When |
111|----------|----------|
112| useState/useReducer | Local component state |
113| Context | Theme, auth, low-frequency global state |
114| Zustand/Jotai | Simple global state, minimal boilerplate |
115| Redux Toolkit | Complex state, time-travel debugging |
116| React Query/SWR | Server state, caching, background refresh |
117| XState | Complex flows with explicit state machines |
118
119### Performance Essentials
120| Technique | Impact |
121|-----------|--------|
122| Code splitting | Reduce initial bundle |
123| Lazy loading | Defer non-critical |
124| React.memo | Prevent unnecessary re-renders |
125| useMemo/useCallback | Stable references |
126| Virtual lists | Handle large datasets |
127
128## Architecture Characteristics (Pick 3-7)
129
130| Characteristic | Questions to Ask |
131|----------------|------------------|
132| **Scalability** | How many concurrent users? Growth rate? |
133| **Performance** | What's acceptable TTI? LCP target? |
134| **Deployability** | How often do you ship? Independent deploys? |
135| **Testability** | How easy to verify changes? |
136| **Maintainability** | What's the expected lifespan? |
137| **Modularity** | How often do requirements change? |
138
139## Anti-patterns to Avoid
140
141| Anti-pattern | Problem | Fix |
142|--------------|---------|-----|
143| Prop drilling | Tight coupling | Context or state management |
144| God components | Too many responsibilities | Split by concern |
145| Premature optimization | Complexity without evidence | Profile first |
146| Shared mutable state | Race conditions, bugs | Immutable patterns |
147| Monolithic bundle | Slow initial load | Code splitting |
148| Over-fetching | Wasted bandwidth | GraphQL or BFF |
149| LocalStorage tokens by default | XSS turns into account takeover | Prefer httpOnly cookies + CSP (see security refs) |
150| Global store for server data | Cache invalidation pain | Use React Query/SWR for server state |
151
152## Performance Budgets
153
154Budgets must be **calibrated to your users/devices**, but these are good starting points for a “fast by default” app:
155
156| Metric | Target | Needs Work |
157|--------|--------|------------|
158| LCP | <2.5s | 2.5–4s |
159| INP | <200ms | 200–500ms |
160| CLS | <0.1 | 0.1–0.25 |
161| TTFB | <800ms | 800ms–1.8s |
162| Route JS (initial) | <170KB gzip | <300KB gzip |
163
164## Sources
165
166Synthesized from:
167- Learning JavaScript Design Patterns (Osmani, 2023)
168- React in Depth (Barklund, 2024)
169- SPA Design and Architecture (Scott)
170- Single Page Web Applications (Mikowski & Powell)
171- Building Micro-Frontends (Mezzalira)
172- Micro Frontends in Action (Geers)
173- Responsible JavaScript (Wagner)
174- High Performance Browser Networking (Grigorik)
175- Web Performance in Action (Wagner)
176- Frontend Architecture for Design Systems (Godbolt)
177- Fundamentals of Software Architecture (Richards & Ford)
178- Software Architecture: The Hard Parts (Ford et al.)
179- Patterns.dev
majiayu000