masaruk Logo

Frontend Web Architecture – Next.js

Next.js 16 (App Router) + TypeScript + TailwindCSS architecture for MASARUK B2C Web Frontend

1. Purpose of This Document

This document describes the architecture of the MASARUK B2C Web Frontend, built with Next.js 16 using the App Router. It defines:

  • Folder structure
  • Rendering strategy (SSR/SSG/CSR)
  • Data-fetching approach
  • Global state management
  • Authentication handling
  • UI components and design system
  • SEO, routing, localization
  • API integration patterns
  • Error handling & performance rules

This document ensures frontend developers follow a consistent, scalable, and maintainable architecture.

2. Architectural Principles

2.1 SSR-first Approach

  • Trip listing pages → SSR
  • Trip details → SSR
  • Static pages (Privacy, Terms) → SSG
  • User dashboard → CSR (protected routes)

2.2 Strong Separation of Concerns

  • UI components → shadcn/ui + custom components
  • API integration → isolated client modules
  • Page logic → server components (where possible)
  • Shared state → Zustand (for lightweight states)

2.3 Strict TypeScript Everywhere

  • All API responses typed
  • All components strongly typed
  • Shared types imported from types/ folder

2.4 Mobile-first Responsive Layout

Using TailwindCSS and consistent design specs: Typography, spacing, layout grid, color tokens. All follow identity defined in ui-ux-guidelines.md.

4. Routing & Navigation (Next.js App Router)

4.1 Public Routes

//trips/trips/[id]/about/contact

4.2 Protected Routes

/bookings/bookings/[id]/profile/payments/*

If user is not authenticated → redirect to /auth/login

4.3 Middleware (Edge Runtime)

  • Token validation
  • Role check (end-user only for B2C web)
  • Locale detection (AR/EN)

7. Authentication Handling

  1. Login via /auth/login
  2. Token stored in HTTP-only cookie or localStorage
  3. middleware.ts validates token on protected routes
  4. useAuth() hook provides current user + logout

8. Localization (AR/EN)

8.1 Approach

  • Language toggle in header
  • RTL layout for Arabic
  • Content translations via JSON or i18n library
  • URL-based locale (optional: /ar/, /en/)

8.2 RTL Handling

Tailwind RTL plugin + conditional classes

11. Summary

The MASARUK Web Frontend is:

Next.js 16 App Router-basedTypeScript-firstSSR-optimized for SEOFully localized (AR/EN + RTL)API-driven via isolated clientsComponent-driven with shadcn/uiReady for scale