flights_web/AGENTS.md

AGENTS.md — Aeroflot.Flights.Web

Quick Start

# Install dependencies
pnpm install

# Development servers
pnpm dev          # Modern.js on :8081
pnpm dev:full     # Proxy on :8080 (API forwarding via curl to bypass WAF)

# Build targets
pnpm build:standalone  # SSR server at dist/standalone/
pnpm build:remote      # MF remote at dist/remote/ (with mf-manifest.json)
pnpm build:both        # Both targets

# Quality checks (run in order)
pnpm typecheck
pnpm lint
pnpm test
pnpm test:coverage
pnpm bundle-size      # CI gate: total gzip ≤ 2000 kB
pnpm check-coverage   # CI gate: line coverage ≥ 65%

# E2E tests
pnpm test:e2e                 # React app (port 8080)
pnpm test:e2e:angular         # Angular app (port 4203)

Architecture

Stack: Modern.js 2.70.8 (Rspack), React 18.2, Module Federation 2.3.3

Source structure:

• src/routes/ — File-based routing (React Router v7)
• src/features/ — Feature modules (online-board, schedule, flights-map, popular-requests)
• src/ui/ — Reusable UI primitives (never import routes/mf from here)
• src/shared/ — Cross-cutting concerns (API client, SignalR, storage, hooks)
• src/observability/ — Logger, metrics (OTel), analytics
• src/i18n/ — Internationalization (9 languages)

Entry points:

• src/routes/page.tsx — Root redirect to /{lang}/onlineboard
• src/routes/layout.tsx — Root layout with global providers
• src/routes/[lang]/layout.tsx — Locale-scoped layout with i18n

Module Federation:

• Remote name: aeroflot_flights
• Exposes: ./OnlineBoard, ./Schedule, ./FlightsMap, ./PopularRequests
• mf-manifest.json at https://<domain>/mf-manifest.json

Critical Constraints

1. Side-effect-free components — No fetch outside useEffect. API calls via ApiClient from context.

2. Dynamic imports — Use React.lazy() for code splitting. Wrap browser-only components (Leaflet) in ClientOnly.

3. SSR safety — SignalR (@microsoft/signalr) is dynamically imported. Never import in SSR bundle (routes/, server/).

4. Layered architecture — Enforced by ESLint:

   • features/ → cannot import routes/ or mf/
   • ui/ → cannot import features/, routes/, mf/
   • shared/ → cannot import features/, routes/, mf/, observability/
   • observability/ → cannot import features/, routes/, mf/

5. Restricted imports (ESLint rules):

   • OTel SDK → use @/observability/metrics/otel (getMeter/getTracer)
   • react-i18next → use @/i18n/provider
   • localStorage/sessionStorage → use @/shared/storage

6. Environment variables — Read via getEnv() from @/env/index.ts. SSR injects window.__ENV__.

Dev Server Details

• Port 8081 — Modern.js dev server (SSR + HMR)
• Port 8080 — pnpm dev:full proxy with:
  • /api/* and /flights/* → https://flights.test.aeroflot.ru (via curl to bypass WAF)
  • /* → Modern.js on 8081

Testing

• Unit tests — Vitest (globals enabled, V8 coverage)
• E2E tests — Playwright (baseURL: http://localhost:8080)
• Angular E2E — Separate config for legacy app (port 4203)

Coverage gates:

• Line coverage ≥ 65%
• Bundle size (gzip) ≤ 2000 kB for remote target

Build Artifacts

• dist/standalone/ — SSR server (Node entrypoint)
• dist/remote/ — MF remote with mf-manifest.json
• dist/remote/static/js/ — JS bundles for bundle-size gate

Deployment

• Standalone — Dockerfile.react (Node 24-slim, serves SSR)
• Remote — Dockerfile.remote (nginx serving static files)
• CI/CD: .github/workflows/ci.yml, .github/workflows/deploy.yml

Known Constraints

• Modern.js 3.x blocked by @module-federation/modern-js ESM incompatibilities
• React Router v7 future flags enabled to suppress deprecation warnings
• Legacy Angular 12 SPA in ClientApp/ (read-only reference)

Commit Rules

• No Co-Authored-By lines
• English commit messages, focus on "why" not "what"
• Commit autonomously when stable; ask before pushing/force-pushing