Frontend Architecture Frontend Architecture Document Project: {{PROJECT_NAME}} Version: {{VERSION}} Date: {{DATE}} Author: {{AUTHOR}} Status: Draft | In Review | Approved Reviewers: {{REVIEWERS}} Document History Version Date Author Changes 0.1 {{DATE}} {{AUTHOR}} Initial draft 1. Purpose & Scope This document defines the frontend architecture for {{PROJECT_NAME}} . It covers framework decisions, folder structure, rendering strategy, routing, build configuration, performance targets, and operational considerations. TODO: Define scope boundaries — which client applications are covered (web app, admin panel, marketing site, etc.). 2. Framework Choice & Rationale Criterion Weight Next.js Nuxt 3 SvelteKit Remix Team expertise 30% {{SCORE}} {{SCORE}} {{SCORE}} {{SCORE}} Ecosystem maturity 25% {{SCORE}} {{SCORE}} {{SCORE}} {{SCORE}} Performance 20% {{SCORE}} {{SCORE}} {{SCORE}} {{SCORE}} DX / tooling 15% {{SCORE}} {{SCORE}} {{SCORE}} {{SCORE}} License / cost 10% {{SCORE}} {{SCORE}} {{SCORE}} {{SCORE}} Selected Framework: {{FRAMEWORK}} Rationale: TODO: Write 3-5 sentences explaining the final decision. Node/runtime version: {{NODE_VERSION}} Package manager: {{npm | yarn | pnpm | bun}} 3. Project Folder Structure {{PROJECT_NAME}}/ ├── src/ │ ├── app/ # Route segments (App Router) or pages/ │ ├── components/ │ │ ├── ui/ # Primitive design system components │ │ ├── features/ # Feature-scoped composite components │ │ └── layouts/ # Page layout wrappers │ ├── hooks/ # Shared custom hooks / composables │ ├── lib/ # Pure utilities, third-party wrappers │ ├── stores/ # Client state (Zustand / Pinia slices) │ ├── services/ # API client, data-fetching layer │ ├── styles/ # Global CSS, theme tokens │ ├── types/ # TypeScript interfaces & enums │ └── constants/ # App-wide constants ├── public/ # Static assets served at root ├── tests/ │ ├── unit/ │ ├── integration/ │ └── e2e/ ├── .env.example ├── next.config.ts # (or framework config file) └── package.json TODO: Update tree to match actual project structure. 4. Rendering Strategy Page Type Strategy Rationale Marketing / landing SSG Maximum caching, no auth dependency Dashboard / app views SSR Fresh data, auth-gated Listing pages ISR (revalidate: 60s) Balance freshness vs performance User-specific views CSR Dynamic, personalized data API routes Server Thin BFF layer Hydration approach: {{Partial hydration | Full hydration | Islands}} TODO: Map every top-level route to a rendering strategy. 5. Routing Architecture 5.1 Route Organization / → Home (SSG) /app/ → App shell (SSR, auth-required) /app/dashboard → Dashboard /app/[resource]/[id] → Dynamic resource detail /api/ → API routes (BFF) /auth/login → Login (CSR) /[...catchAll] → 404 handler 5.2 Route Guards / Middleware Middleware execution order: 1. Request logging 2. Authentication check (JWT validation / session lookup) 3. Redirect unauthenticated → /auth/login 4. Role-based route protection 5. Locale detection / redirect TODO: List all protected route patterns and their required roles. 6. Build & Bundle Configuration 6.1 Key Config Options Option Value Reason Output standalone Docker-optimized deployment Image optimization Enabled Next/Image with defined domains Bundle analyzer ANALYZE=true On-demand local analysis Source maps Production: hidden Security — upload to Sentry only Compression gzip + brotli CDN-level, not server-level 6.2 Code Splitting Strategy Route-level splitting: Automatic per page/route segment Component-level splitting: dynamic() / defineAsyncComponent() for modals, heavy widgets Third-party splitting: Vendor chunk isolation for large deps (charts, editors) TODO: Identify and document specific lazy-loaded components. 7. Performance Budget Metric Target Tool LCP (Largest Contentful Paint) < 2.5s Lighthouse, CrUX FID / INP (Interaction to Next Paint) < 200ms CrUX CLS (Cumulative Layout Shift) < 0.1 Lighthouse TTFB (Time to First Byte) < 600ms WebPageTest Total JS bundle (compressed) < 200 KB Bundlesize CI check First page load (mobile 4G) < 3s WebPageTest Lighthouse Performance Score ≥ 90 Lighthouse CI CI enforcement: TODO: link to bundlesize config or Lighthouse CI workflow 8. Asset Management 8.1 Images Format: WebP primary, JPEG fallback, SVG for vector Optimization: Framework image component ( next/image / nuxt/image ) CDN: {{CDN_PROVIDER}} — origin: {{STORAGE_BUCKET}} Lazy loading: Native loading="lazy" + framework component 8.2 Fonts Self-hosted via /public/fonts/ (no Google Fonts runtime requests) font-display: swap on all faces Subset to used characters if possible 8.3 Icons Library: {{Lucide | Heroicons | custom SVG sprite}} Delivery: Inline SVG via component (no icon font) TODO: Finalize CDN domain and storage bucket configuration. 9. Internationalization (i18n) Strategy Item Decision Library `{{next-intl Locale routing /[locale]/path prefix Default locale {{en}} Supported locales {{en, nb, de}} Translation format JSON key-value (per locale, per namespace) Translation storage src/messages/[locale]/[namespace].json Pluralization ICU message format RTL support `{{Yes Translation workflow: Developer adds key with English string TODO: extraction tool generates translation keys Translator fills missing keys in Phrase/Lokalise/manual JSON CI validates no missing keys before deploy 10. Error Boundary Strategy Level Scope Behavior Global error.tsx Full page crash Show branded error page, report to Sentry Layout boundary Section crash Isolate — rest of page remains usable Async component Data fetch failure Skeleton → error state UI Form submission Mutation failure Inline error message + retry Error reporting: {{Sentry | Datadog | custom}} DSN: {{SENTRY_DSN}} (environment variable — never hardcode) TODO: Implement and test each boundary level. 11. Environment Configuration Variable Dev Staging Prod Description NEXT_PUBLIC_API_URL http://localhost:4000 https://api-staging.{{DOMAIN}} https://api.{{DOMAIN}} Backend API base URL NEXT_PUBLIC_APP_ENV development staging production Runtime environment flag SENTRY_DSN optional required required Error reporting (server-side) NEXT_PUBLIC_SENTRY_DSN optional required required Error reporting (client-side) ANALYZE true/false — — Enable bundle analyzer Secrets management: All non-public secrets stored in {{Vault / AWS Secrets Manager / Vercel env}} . .env.example : Must be kept up to date — CI validates no undocumented variables exist. 12. Dependency Management Policy Rule Detail Approval required for new deps PR must include: bundle size impact, license check, last release date Allowed licenses MIT, Apache-2.0, ISC, BSD-2, BSD-3 Security audit npm audit / pnpm audit in CI — fail on high/critical Update cadence Minor/patch: monthly automated PR (Renovate); Major: manual + reviewed Banned patterns No moment.js (use date-fns ), no lodash (use native / lodash-es ) TODO: Configure Renovate or Dependabot with appropriate grouping rules. 13. Architecture Diagram graph TB subgraph "Client Browser" Browser["User Browser"] end subgraph "Frontend Application — {{FRAMEWORK}}" CDN["CDN Edge (Static Assets)"] SSR["SSR Server / Edge Runtime"] Pages["Route Segments / Pages"] Components["Component Tree"] State["State Layer (Server + Client)"] Services["API Service Layer"] end subgraph "Backend" API["REST / GraphQL API"] Auth["Auth Service"] end Browser --> CDN Browser --> SSR SSR --> Pages Pages --> Components Components --> State State --> Services Services --> API SSR --> Auth TODO: Refine diagram to reflect actual deployed infrastructure (Vercel, AWS, self-hosted, etc.). Approval Role Name Date Signature Author Tech Lead Architect Engineering Manager