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:

1. Clarify context (5–10 questions max) → users, routes, SEO, interactivity, data, auth, team, constraints.
2. Choose a rendering strategy per route (not “one strategy for the whole app”).
3. Define boundaries → feature/domain modules, shared libraries, ownership, and stable interfaces.
4. Plan state + data → local/shared/global/server/URL state, cache strategy, invalidation, optimistic updates.
5. Plan non-functionals → performance budgets + measurement, accessibility plan, security posture, observability.
6. 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

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

State Management

Performance Essentials

Architecture Characteristics (Pick 3-7)

Anti-patterns to Avoid

Performance Budgets

Budgets must be calibrated to your users/devices, but these are good starting points for a “fast by default” app:

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