126 lines
6.3 KiB
Markdown
126 lines
6.3 KiB
Markdown
# Phase 1 — Foundation
|
|
|
|
Phase 1 builds the complete Modern.js + Module Federation 2.0 foundation for the Aeroflot Flights Web rewrite. Nothing in Phase 1 ships to production users — the output is a working dual-build artifact (standalone SSR + MF 2.0 remote) with all observability, security, and CI pipelines live.
|
|
|
|
## What Phase 1 shipped
|
|
|
|
Phase 1 consists of 14 sub-plans, each with its own implementation plan under `docs/superpowers/plans/`:
|
|
|
|
| ID | Sub-plan | Description |
|
|
|---|---|---|
|
|
| **1A-1** | Project skeleton | `src/` tree, tsconfig, eslint base, zod-validated env config, package.json |
|
|
| **1A-2** | MF 2.0 + dual builds | Module Federation 2.0 config, standalone + remote build targets, RemoteLoader, MF spike |
|
|
| **1A-3** | ESLint boundaries | Layered dependency rules enforcing `shared/ -> features/ -> routes/` direction |
|
|
| **1B** | CI pipeline | GitHub Actions workflow: typecheck, lint, test, coverage, build, MF manifest validation, security audit |
|
|
| **1C** | i18n runtime | i18next + ICU MessageFormat, 9 locales, locale resolver, serializer |
|
|
| **1D** | API client | Fetch-based client with retry, circuit breaker, LRU cache, zod validation |
|
|
| **1E** | SignalR wrapper | Reconnecting SignalR connection with `useLiveFlights` hook for real-time board updates |
|
|
| **1F-layout** | Root layout | Root + locale layouts, error routes, smoke route, ErrorBoundary, HTTP error mapper |
|
|
| **1F-seo** | SEO primitives | `SeoHead` component, hreflang builder, `JsonLdRenderer` for structured data |
|
|
| **1G-logger** | Logger | Structured JSON-lines transport + console transport, logger provider |
|
|
| **1G-metrics** | Metrics | OpenTelemetry init (server MeterProvider + TracerProvider), custom metric instruments |
|
|
| **1G-analytics** | Analytics | Analytics facade with four stub adapters (Yandex.Metrica, CTM, Variocube, Dynatrace) |
|
|
| **1H** | Security | CSP with per-request nonce, stream-transform nonce injection, HTTP security headers, secure storage |
|
|
| **1I** | Deploy pipeline | Dockerfile pair, health endpoint, graceful shutdown, deploy workflow, runbook |
|
|
|
|
## Running locally
|
|
|
|
### Prerequisites
|
|
|
|
- Node.js 24.2.0+ (see `.nvmrc`)
|
|
- pnpm 9+
|
|
|
|
### Commands
|
|
|
|
```bash
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Start dev server (standalone SSR mode)
|
|
pnpm dev
|
|
|
|
# Build both targets
|
|
pnpm build:both
|
|
|
|
# Run tests
|
|
pnpm test
|
|
|
|
# Run tests with coverage
|
|
pnpm test:coverage
|
|
|
|
# Lint
|
|
pnpm lint
|
|
|
|
# Typecheck
|
|
pnpm typecheck
|
|
|
|
# Check bundle size
|
|
pnpm bundle-size
|
|
```
|
|
|
|
### Build targets
|
|
|
|
- **Standalone** (`pnpm build:standalone`): Full SSR app with its own server, routes, and HTML shell. Output in `dist/standalone/`.
|
|
- **Remote** (`pnpm build:remote`): MF 2.0 remote component exposing `OnlineBoard`, `Schedule`, `FlightsMap`, `PopularRequests`. Output in `dist/remote/`, serves `mf-manifest.json` at root.
|
|
|
|
### Environment variables
|
|
|
|
All env vars are validated at startup via zod (see `src/env/index.ts`). Required variables for local dev are set to defaults. For full configuration, see the env schema.
|
|
|
|
Key variables:
|
|
- `BUILD_TARGET` — `standalone` or `remote` (set by build scripts)
|
|
- `OTEL_EXPORTER_OTLP_ENDPOINT` — OpenTelemetry collector endpoint (optional for dev)
|
|
- `LOG_LEVEL` — `debug`, `info`, `warn`, `error` (default: `info`)
|
|
|
|
## Debugging common failures
|
|
|
|
### SSR fallback
|
|
|
|
**Symptom:** Page renders as empty white screen, then client-side hydration kicks in late.
|
|
|
|
**Cause:** An error during SSR caused React to fall back to client-only rendering.
|
|
|
|
**Debug:**
|
|
1. Check server logs for SSR errors — they appear as structured JSON lines with `"level":"error"`.
|
|
2. Common culprits: accessing `window`/`document` during SSR, missing env vars, API calls outside `useEffect`.
|
|
3. The `ErrorBoundary` catches render errors and shows a fallback UI. Check the error boundary's `componentDidCatch` output in logs.
|
|
|
|
### Missing env vars
|
|
|
|
**Symptom:** App crashes at startup with a zod validation error.
|
|
|
|
**Debug:**
|
|
1. Read the error message — it lists exactly which env vars failed validation.
|
|
2. Check `src/env/index.ts` for the full schema and defaults.
|
|
3. For local dev, most vars have sensible defaults. For deployed environments, ensure all required vars are set in the deployment config.
|
|
|
|
### ESLint boundary violations
|
|
|
|
**Symptom:** `pnpm lint` fails with `boundaries/element-types` or `boundaries/entry-point` errors.
|
|
|
|
**Debug:**
|
|
1. The boundary rules enforce a strict layering: `shared/` and `observability/` cannot import from `features/` or `routes/`. `features/` cannot import from `routes/` or `mf/`. `ui/` cannot import from `features/`.
|
|
2. If you need shared logic, move it to `shared/`. If you need a feature-specific component, keep it in `features/<name>/components/`.
|
|
3. Run `pnpm lint` with `--debug` for detailed rule information.
|
|
4. See `eslint.config.js` for the full boundary configuration.
|
|
|
|
### Test flakes
|
|
|
|
**Symptom:** Tests pass locally but fail intermittently in CI.
|
|
|
|
**Known flaky patterns:**
|
|
1. **Timer-based tests** (SignalR reconnection, circuit breaker): These use `vi.useFakeTimers()`. Ensure `vi.advanceTimersByTime()` is called with exact intervals, not approximate.
|
|
2. **ESLint integration tests** (`tests/eslint/`): These spawn real ESLint processes and can be slow (~20s each). They are not flaky but may time out on constrained CI runners. The CI timeout is 20 minutes to accommodate this.
|
|
3. **OpenTelemetry tests**: The `otel.test.ts` suite registers global providers. Each test must clean up after itself to avoid state leakage.
|
|
|
|
**General tips:**
|
|
- Run `pnpm test -- --reporter=verbose` to see timing for each test.
|
|
- Use `pnpm test -- --bail 1` to stop on first failure for faster feedback.
|
|
|
|
## Related documents
|
|
|
|
- **Runbook:** [`docs/superpowers/phase-1/runbook.md`](runbook.md) — Operational runbook for incident response, health checks, rollback procedures, and monitoring dashboards.
|
|
- **Cutover plan:** [`docs/superpowers/plans/2026-04-15-phase-6-cutover.md`](../plans/2026-04-15-phase-6-cutover.md) — Production cutover strategy including canary deploy, traffic shifting, and rollback gates.
|
|
- **Design spec:** [`docs/superpowers/specs/2026-04-14-aeroflot-flights-react-rewrite-design.md`](../specs/2026-04-14-aeroflot-flights-react-rewrite-design.md) — Full design specification for the Angular-to-React rewrite.
|
|
- **Phase 1 master plan:** [`docs/superpowers/plans/2026-04-14-phase-1-foundation-master.md`](../plans/2026-04-14-phase-1-foundation-master.md) — Sub-plan index with dependency graph and contracts.
|