booking-ewa/docs/ARCHITECTURE.md

Architecture

System Overview

The Booking EWA is a two-tier application:

1. Express Backend (Node.js, TypeScript) -- Runs on port 3001. Handles JWT authentication, session management, and proxies all API calls to the AMPECO public API. The frontend never communicates with the public API directly.

2. React SPA Frontend (Vite, TypeScript, Tailwind CSS) -- Runs on port 5173 in development. A single-page application using HashRouter for client-side navigation. Styled with @ampeco/design-tokens CSS custom properties and @ampeco/ewa-ui Tailwind plugin.

graph LR
    MobileApp["Mobile App"] -->|JWT in X-Payload header| Backend["Express Backend :3001"]
    Backend -->|Bearer token auth| PublicAPI["AMPECO Public API"]
    Browser["Browser / WebView"] -->|fetch /api/*| ViteDev["Vite Dev Server :5173"]
    ViteDev -->|proxy| Backend

In production, the Vite dev server is replaced by static file serving. The built frontend assets are in dist/.

---

Backend Architecture

Entry Point

File: backend/src/index.ts

The Express server configures CORS (for localhost:5173 during dev), JSON body parsing, JWT middleware, and mounts the route handler.

JWT Middleware Flow

Every incoming request passes through the JWT middleware:

flowchart TD
    A[Request arrives] --> B{X-Payload header present?}
    B -->|Yes| C[Verify JWT with HS256]
    C -->|Valid| D[Set req.session from JWT payload]
    C -->|Invalid| E{NODE_ENV === development?}
    B -->|No| E
    E -->|Yes| F[Set req.session to dev fallback]
    E -->|No| G[req.session remains undefined]
    D --> H[next]
    F --> H
    G --> H

The JWT token is expected in the X-Payload HTTP header (not Authorization). This is the convention used by the mobile app when embedding the EWA in a WebView.

JWT Payload Structure (backend/src/types.ts):

interface JwtPayload {
  iss: string;
  aud: string;
  iat: number;
  nbf: number;
  exp: number;
  payload: {
    type: string;              // "ewa"
    timestamp: string;
    appVersionCode: string;
    parameters: {
      userId?: number | null;
      operatorId: number;
      appLanguage: string;     // e.g. "en"
      appCountry: string;      // e.g. "US"
      appTheme: 'LIGHT' | 'DARK';
      designTokens?: Record<string, string>;
    };
  };
}

The middleware extracts parameters into a SessionData object stored on req.session.

Dev Fallback Session:

When NODE_ENV=development and no valid JWT is present, the backend injects a default session:

{
  userId: 775,
  operatorId: 1,
  appLanguage: 'en',
  appCountry: 'US',
  appTheme: 'LIGHT',
}

API Proxy Pattern

File: backend/src/proxy.ts

The proxyRequest function forwards requests from the frontend to the AMPECO public API. It:

1. Constructs the full URL from API_BASE_URL + the target path.
2. Forwards query parameters (for GET requests) and maps route parameters.
3. Attaches the Authorization: Bearer <API_TOKEN> header.
4. Forwards the request body for non-GET methods.
5. Returns the upstream response status and body to the client.
6. Returns 502 Bad Gateway on network errors.

The frontend never sees the API_TOKEN -- it is server-side only.

Route Mapping

File: backend/src/routes.ts

Frontend Path	Method	Upstream Public API Path
GET /api/session	--	No proxy. Returns req.session directly.
GET /api/bookings	GET	/resources/bookings/v1.0
GET /api/bookings/:id	GET	/resources/bookings/v1.0/:id
POST /api/booking-requests	POST	/resources/booking-requests/v1.0
POST /api/locations/:id/check-availability	POST	/actions/locations/v2.0/:id/check-booking-availability
POST /dev/jwt (dev only)	--	No proxy. Creates and returns a dev JWT token.

Session Data Flow

The /api/session endpoint does not proxy to the upstream API. It returns the session data extracted from the JWT by the middleware, which the frontend uses to:

• Identify the current user (userId).
• Apply the correct theme (appTheme + designTokens).
• Set the UI language (appLanguage).

---

Frontend Architecture

Application Bootstrap

File: src/main.tsx

1. i18next is initialized (src/i18n/init.ts).
2. Global CSS is loaded (src/app.css -- imports @ampeco/design-tokens/css/variables.css and Tailwind).
3. <App /> is rendered into #root.

Component Tree

<App>
  <SessionProvider>            -- Fetches /api/session, applies theme, provides context
    <AppContent>               -- Guards on loading/error/userId
      <AppRouter>              -- HashRouter with Layout wrapper
        <Layout>               -- App shell with bottom nav (Home | Book | My Bookings)
          <Home />             -- Route: /
          <CreateBooking />    -- Route: /create
          <MyBookings />       -- Route: /bookings
          <BookingDetail />    -- Route: /bookings/:id
          <UpdateBooking />    -- Route: /bookings/:id/update
        </Layout>
      </AppRouter>
    </AppContent>
    -- OR (if no userId) --
    <UserIdFallback />         -- Manual user ID entry screen
  </SessionProvider>
</App>

Page Routing

File: src/router/index.tsx

Uses HashRouter (URLs like /#/bookings/123) for compatibility with WebView environments that may not support HTML5 history API.

Route	Component	Description
/#/	Home	Dashboard with upcoming bookings
/#/create	CreateBooking	Two-step booking creation
/#/bookings	MyBookings	Upcoming/Past booking tabs
/#/bookings/:id	BookingDetail	Single booking detail + actions
/#/bookings/:id/update	UpdateBooking	Edit booking time range

All routes are wrapped in the <Layout> component which provides a fixed bottom navigation bar with three tabs: Home, Book a Charger, and My Bookings.

State Management

State is managed through React Context and local component state. There is no external state management library.

SessionContext (src/context/SessionContext.tsx):

• Fetches session data from /api/session on mount.
• Applies the theme by dynamically importing @ampeco/design-tokens and calling applyTheme(appTheme, designTokens).
• Provides session, loading, error, and setManualUserId to all child components.
• setManualUserId allows overriding the userId in the session (used by UserIdFallback in dev mode).

useSession (src/hooks/useSession.ts):

Convenience hook that calls useContext(SessionContext).

Data Fetching Hooks

useBookings (src/hooks/useBookings.ts):

• useBookings(params) -- Fetches a list of bookings with optional filter parameters (userId, status, date range, pagination). Loads once on mount.
• useBookingDetail(id) -- Fetches a single booking by ID. Includes a polling mechanism that refreshes every 30 seconds. Polling:
  • Pauses when the browser tab is hidden (document.hidden).
  • Resumes immediately when the tab becomes visible.
  • Stops permanently when the booking reaches a terminal status (completed, cancelled, no-show, failed).

useAvailability (src/hooks/useAvailability.ts):

• Provides a check(locationId, startAfter, endBefore) function for on-demand availability queries.
• Returns slots, loading, error, and a reset function.
• No automatic polling.

API Client Layer

File: src/api/client.ts

A thin fetch wrapper that:

1. Prepends /api to all paths (which Vite proxies to the backend).
2. Sets Accept: application/json and Content-Type: application/json headers.
3. Throws ApiRequestError on non-2xx responses, preserving the HTTP status and parsed response body.

export class ApiRequestError extends Error {
  status: number;
  body: Record<string, unknown> | null;

  get isNotFound(): boolean;
  get isForbidden(): boolean;
  get isValidationError(): boolean;   // status === 422
  get isUnauthorized(): boolean;
  get validationErrors(): Record<string, string[]>;  // body.errors
}

Endpoint modules:

Module	Functions
src/api/bookings.ts	fetchBookings(params), fetchBooking(id)
src/api/bookingRequests.ts	createBookingRequest(payload) -- handles create, update, cancel
src/api/availability.ts	checkAvailability(locationId, payload)

The createBookingRequest function accepts a discriminated union payload:

type BookingRequestPayload =
  | { type: 'create'; userId: number; locationId: number; startAt: string; endAt: string; evseCriteria?: {...} }
  | { type: 'update'; bookingId: number; startAt: string; endAt: string }
  | { type: 'cancel'; bookingId: number }

Design Token Integration

flowchart LR
    A[JWT payload] -->|designTokens + appTheme| B[SessionContext]
    B -->|applyTheme| C["@ampeco/design-tokens"]
    C -->|Sets CSS custom properties| D["document.documentElement.style"]
    D -->|var(--btn-primary-bg), etc.| E[All components]

1. The JWT payload carries appTheme ('LIGHT' or 'DARK') and an optional designTokens map of CSS custom property overrides.
2. SessionContext calls applyTheme(appTheme, designTokens) from @ampeco/design-tokens after fetching the session.
3. applyTheme sets CSS custom properties on the document root element.
4. All components reference these variables via inline styles (e.g., var(--btn-primary-bg, #2563eb)) with hardcoded fallback values.
5. The base CSS variables are imported in src/app.css from @ampeco/design-tokens/css/variables.css.

Key CSS custom properties used throughout the UI:

Variable	Usage
--surface-elevation-0	Page background
--surface-elevation-1	Card/input backgrounds
--surface-elevation-2	Elevated slot buttons
--text-primary	Primary text color
--text-secondary	Secondary/muted text
--btn-primary-bg	Primary button background
--btn-primary-text	Primary button text color
--border-default	Border color for cards, inputs

Internationalization

File: src/i18n/init.ts

Uses i18next with react-i18next. Currently ships with English (en) translations only. Translation strings are organized by feature in src/i18n/locales/en.json.

Components access translations via the useTranslation() hook:

const { t } = useTranslation();
// t('createBooking.title') --> "Book a Charger"

Tailwind CSS Configuration

File: tailwind.config.ts

• Content sources: index.html, all src/**/*.{ts,tsx}, and compiled @ampeco/ewa-ui dist files.
• Plugins: ewaUiPlugin from @ampeco/ewa-ui/plugin (provides shared component styles).

---

Data Flow Diagrams

JWT to Session to Theme

sequenceDiagram
    participant App as Mobile App
    participant WV as WebView
    participant BE as Express Backend
    participant API as AMPECO API

    App->>WV: Load EWA URL with X-Payload JWT header
    WV->>BE: GET /api/session (X-Payload: <jwt>)
    BE->>BE: Verify JWT (HS256)
    BE->>WV: 200 { userId, operatorId, appTheme, designTokens, ... }
    WV->>WV: SessionContext.applyTheme(appTheme, designTokens)
    WV->>WV: Set CSS custom properties on :root
    WV->>WV: Render app with themed components

Booking CRUD Flow

sequenceDiagram
    participant UI as React Frontend
    participant BE as Express Backend
    participant API as AMPECO Public API

    Note over UI: Create Booking (2-step)
    UI->>BE: POST /api/locations/:id/check-availability
    BE->>API: POST /actions/locations/v2.0/:id/check-booking-availability
    API-->>BE: { data: AvailabilitySlot[] }
    BE-->>UI: Available slots

    UI->>BE: POST /api/booking-requests { type: "create", ... }
    BE->>API: POST /resources/booking-requests/v1.0
    API-->>BE: { data: BookingRequest { status: "approved", bookingId } }
    BE-->>UI: Booking confirmed

    Note over UI: Read / Poll
    UI->>BE: GET /api/bookings/:id
    BE->>API: GET /resources/bookings/v1.0/:id
    API-->>BE: { data: Booking }
    BE-->>UI: Booking detail (polls every 30s)

    Note over UI: Update Booking
    UI->>BE: POST /api/booking-requests { type: "update", bookingId, startAt, endAt }
    BE->>API: POST /resources/booking-requests/v1.0
    API-->>BE: { data: BookingRequest { status: "approved" } }
    BE-->>UI: Update confirmed

    Note over UI: Cancel Booking
    UI->>BE: POST /api/booking-requests { type: "cancel", bookingId }
    BE->>API: POST /resources/booking-requests/v1.0
    API-->>BE: { data: BookingRequest }
    BE-->>UI: Cancellation confirmed

---

Type System

Backend Types (backend/src/types.ts)

• JwtPayload -- Full JWT structure with nested payload.parameters.
• SessionData -- Flattened session data extracted from the JWT.

Frontend Types (src/types/index.ts)

• Booking -- Core booking entity with id, userId, locationId, startAt, endAt, status, optional bookedEvses, authorizedTokens, accessMethods, sessionId.
• BookingStatus -- Union type: 'accepted' | 'reserved' | 'completed' | 'cancelled' | 'no-show' | 'failed'.
• BookingRequest -- Result of a booking request operation (type: 'create' | 'update' | 'cancel', status: 'approved' | 'rejected').
• AvailabilitySlot -- EVSE availability data with evseId and array of { startAt, endAt } slots.
• SessionData -- Mirror of the backend SessionData type.

---

Build and Deployment

Development

npm run dev runs two processes concurrently:

1. vite -- Frontend dev server on port 5173 with HMR. Proxies /api/* and /dev/* to localhost:3001.
2. tsx watch backend/src/index.ts -- Backend with hot-reload via tsx.

Production Build

npm run build executes:

1. vite build -- Bundles the React frontend into dist/ (HTML, JS, CSS assets).
2. tsc -p backend/tsconfig.json -- Compiles the backend TypeScript into dist/backend/.

The production deployment serves dist/ as static files and runs the compiled backend.