Solutions
The solutions used to build, serve and observe HAIH: what each provides, what adopting it requires and what remains open.
Start directly with npm run dev, or build and serve with npm run build then npm run start. Docker, Traefik, Varnish and monitoring are deployment choices. The current application uses Express, GraphQL and React Router server rendering alongside built pages and assets.
Nesting shows composition within each layer. Dependencies across layers are stated explicitly. “In use” describes this repository; it does not claim a comparative benchmark or complete verification.
One server can share its Traefik and monitoring across multiple sites. Monitoring services currently live in the base Compose configuration; there is no dedicated optional profile yet.
Our direction pairs performance with openness to AI and other bots. Monitoring is implemented; selective blocking and separate traffic classification remain local policy work. Read Open to bots. Closed to abuse. and the field note on verification boundaries.
The development proxy serves the same app over HTTP and HTTPS at once. Both views receive React updates through their own page port; development Varnish passes requests without caching. Read Two protocols. One development loop. for the local browser check and setup requirements.
Application — components, navigation and rendering
React components form the pages. React Router connects browser navigation with prerendering and the application server.
React — In use
Provides: Reusable components, UI state and hydration of generated HTML.
Requirements and limits
React DOM and a browser for client execution; the build also renders public pages in Node.js.
React Router — In use; also integrates with the build
Provides: Routes, SPA navigation, metadata integration, lazy route modules, error boundaries and build-time page rendering. Vite alone does not provide this complete integration.
Requirements and limits
React, its Vite integration and Node.js. The current configuration enables request-time SSR alongside prerendering; Express connects the production server build. Components are not automatically excluded from client JavaScript because they were prerendered.
Development and build — Node.js runs the tools
npm run dev starts development directly. npm run build produces HTML, JavaScript, CSS and the Node.js server. Docker, Traefik and Varnish are not prerequisites.
Node.js + npm — Required by the current toolchain
Provides: The runtime and package workflow used to install dependencies, run development tools and build the application.
Requirements and limits
The supported Node.js version, package.json and the lockfile. Our Vite toolchain runs on Node.js, not inside the browser or Docker itself.
Vite — In use as Express middleware with React Router
Provides: A development server with HMR, module and asset processing, production bundles and code splitting. It covers these needs without a custom build pipeline; it is not the production HTTP server.
Requirements and limits
Node.js, source modules and configuration. Vite shares the application HTTP listener for HMR at /__vite_hmr; the browser uses its page host, port and WS/WSS protocol. React Router supplies routing and prerendering. A React edit was checked over simultaneous local HTTP and HTTPS connections; this does not establish every style or state-preservation case.
Linaria + WyW Vite plugin — In use; focused verification continues
Provides: Styled-component references inside selectors while extracting CSS during the build. This styling requirement exists now, which is why Linaria was introduced now.
Requirements and limits
The Vite transform and statically extractable styles. Page and layout wrappers use Linaria styled components with CSS extracted during the build. Color and new-rule edits were checked both directly and through the HTTPS proxy. Cross-file selectors, dynamic values, hydration and lazy CSS delivery still need focused verification; fewer dependencies alone would not make CSS Modules an equivalent substitute.
HTTP and HTTPS development with shared HMR — Implemented; checked in local Chromium
Provides: Open the same running app over HTTP and HTTPS at once. One React source edit updates both views without switching modes or publishing a separate HMR port. Traefik routes the update connection directly to the app; ordinary requests pass through Varnish without caching.
Requirements and limits
For the proxy path: Docker Compose, the configured external network, available ports and a local TLS certificate. Defaults are HTTP 8080, HTTPS 8443 and direct app HTTP 3001. Browser trust is a separate setup step; published ports bind to loopback. The check covered two tabs and a React component edit, not every browser, Linaria update, authentication flow or remote device. Direct npm run dev remains available without this infrastructure.
TypeScript — In use
Provides: Checks component props and integration contracts with npm run types. esbuild bundles the production server separately; a successful bundle does not imply a successful type check.
Requirements and limits
Node.js, type definitions and TypeScript configuration. It does not replace runtime validation.
Storybook — Optional; configured
Provides: An isolated environment for inspecting component states without navigating full pages.
Requirements and limits
React/Vite integration and component stories. Scripts and configuration exist; the story catalog remains to be populated.
ESLint and Prettier — In use
Provides: Code checks and consistent formatting alongside type checking. Behavioral verification is described in the testing layer below.
Requirements and limits
Project rules and configuration. Static checks do not establish browser behavior, API correctness or cache policy.
Verification — checks with explicit environments
Fast unit feedback, local integration checks, browser scenarios and deployed-stack checks have separate commands. A result applies to the behavior and environment it actually exercised.
Vitest — In use; unit and integration suites
Provides: npm test discovers unit tests without a running application. npm run test:integration builds first, then checks generated SEO/HTML, monitoring configuration and a GraphQL error fixture. Watch commands and unit coverage reports are available.
Requirements and limits
Node.js and the test configuration. Integration fixtures use temporary files and local listeners; the integration watcher does not rebuild changed artifacts. Coverage is scoped to configured SEO/server source, not the whole system.
Playwright — In use; focused browser checks
Provides: Tests SPA navigation, history, metadata, heading focus, deep-link refresh and 404 behavior in desktop Chromium, desktop WebKit and mobile Chromium. Failures retain traces and screenshots.
Requirements and limits
Browser binaries and system libraries. npm run e2e normally builds and starts the production Node.js server; PLAYWRIGHT_BASE_URL instead uses a prepared environment. These scenarios do not establish every hydration, accessibility or chunk-recovery behavior.
Production-path and monitoring checks — Configured; require a running stack
Provides: npm run test:integration:stack checks HTTP/cache behavior and the monitoring integration. Controlled failure and notification exercises remain separate explicit commands.
Requirements and limits
A prepared Traefik → Varnish → Node.js environment, monitoring services and local credentials. A passing direct-server test is not evidence about Varnish; notification fixtures do not establish delivery to real recipients.
Production — serve the finished build
Direct path: npm run build → npm run start → Node.js with Express, GraphQL, sirv and the React Router server build. Docker, a reverse proxy and a cache are not required for this direct path.
Node.js HTTP process — In use
Provides: Runs the built application with npm run start, including GraphQL and the React Router request handler. Vite middleware is used only in development.
Requirements and limits
A completed build, Node.js, production dependencies and a reachable port.
Express — In use in development and production
Provides: One application entry point for GraphQL and page handling. Development attaches Vite middleware; production attaches sirv and the React Router server build.
Requirements and limits
Node.js, middleware ordering and shutdown handling. It was adopted for the application/API requirement, not merely to serve files.
GraphQL — Apollo Server + Pothos — Implemented; minimal health API
Provides: A typed server schema, a /api endpoint and an embedded query explorer. The health query establishes API reachability; error instrumentation catches GraphQL failures even with HTTP 200.
Requirements and limits
Express, Apollo Server, Pothos and GraphQL. No database, authorization layer or frontend API client has been added. This API shares the application process rather than running as a standalone service.
sirv — In use
Provides: Serves files from build/client as Express middleware. Requests not served as files reach the React Router handler; the unknown route returns 404.
Requirements and limits
Express and a completed client build. Cache behavior through Varnish comes from its separate VCL policy; direct Node.js serving must not be assumed to have the same cache behavior.
Process supervision — for example PM2 — Optional alternative; not configured
Provides: A possible way to supervise the Node.js service instead of running it as a foreground npm process.
Requirements and limits
A supervisor installation and deployment-specific startup/restart configuration. PM2 is an example, not an adopted or verified project dependency; containers are another deployment choice.
Optional deployment environment — around the application
These are deployment choices, not prerequisites for direct Node.js execution. The configured path is Traefik → Varnish → the Node.js application. A server can share one Traefik and one monitoring installation across multiple sites.
Docker — Optional; configured
Provides: Packages the service environment into container images for repeatable execution.
Requirements and limits
A Docker runtime, images, storage and networking. Native Node.js execution remains possible.
Docker Compose — Optional; configured
Provides: Describes the app, cache, proxy and monitoring services, with shared definitions and development/production overrides.
Requirements and limits
Docker, images, environment variables, the configured external network, available ports and generated monitoring configuration/secrets. Monitoring currently lives in the base Compose file, without an optional profile.
App service container — Configured
Provides: A container boundary around the Node.js application. Development runs Express, GraphQL and Vite middleware; production runs the built server and its runtime dependencies.
Requirements and limits
The Dockerfile and selected environment configuration. Development mounts source files; production uses the built artifact and server dependencies.
Cache service container — Configured for production and development
Provides: Runs Varnish in front of the origin, with separate production caching and development pass policies.
Requirements and limits
The Varnish configuration described below and a reachable app service.
Proxy service container — Configured
Provides: Runs Traefik as a separate entry-point service.
Requirements and limits
The Traefik configuration described below and reachable upstream services.
Traefik — Optional; configured
Provides: A shared entry point, TLS termination and routing to the app or cache. Development exposes HTTP and HTTPS together; /__vite_hmr goes directly to the app while page requests go through Varnish.
Requirements and limits
Routing, network and upstream configuration; TLS needs a certificate matching the requested hostname or IP address and browser trust. The development Compose override selects its own dynamic routing directory. Direct npm run dev does not need Traefik. Local Chromium verified HTTPS delivery and WSS updates through the proxy.
Varnish — Optional; production caching and development pass mode
Provides: Caches eligible public responses to avoid repeated origin requests. This is an additional delivery capability, not a requirement for React, Vite or Node.js.
Requirements and limits
An HTTP origin and VCL rules. The production policy passes /api and non-GET/HEAD requests, avoids caching non-200 responses, and assigns successful responses one hour or matching asset paths seven days. It removes request cookies and response Set-Cookie headers; it is not a finished policy for authenticated or personalized content. Publication invalidation remains open. Direct development access bypasses Varnish. The development proxy path uses a separate VCL that passes every request and returns X-Cache: PASS and Cache-Control: no-store. It does not test production cache hits.
Optional observation — evidence about the running system
Shared operational monitoring and visitor analytics answer different questions. Monitoring observes one server and its registered sites; useful automation must not be confused with malicious traffic.
Betterlytics — Optional integration
Provides: A configured script hook for website usage analytics.
Requirements and limits
A site ID, external service and collection policy. The hook does not prove collection is working and does not measure Varnish origin traffic.
Shared server monitoring — Implemented; exercised in a local production preview
Provides: A site registry, internal page/API probes, metrics, logs and alert rules for several sites behind one Traefik. A controlled app pause showed a cached page staying available while the uncached API failed and recovered.
Requirements and limits
Configured sites, reachable services and persistent storage. Seven monitoring containers used roughly 594–714 MiB in short local observations, not a guaranteed ceiling. Same-host probes cannot independently detect total host failure. Browser errors and bot classification are not collected by this integration.
Monitoring and our open-to-bots strategy
Prometheus — Configured and locally checked
Provides: Stores request rates, statuses, HTTP bytes, latency histograms, probe results and host/application metrics; evaluates alert rules.
Requirements and limits
Scrape targets and storage. Metric retention is 30 days with a 2 GiB TSDB retention limit; temporary WAL/head usage is additional. Missing observations must not be counted as successful uptime.
Grafana — Provisioned dashboard; locally checked
Provides: A site selector and views for availability, probe coverage, response times, errors, resources and logs.
Requirements and limits
Prometheus, Loki and provisioned data sources. Login is required; the configured host port binds to loopback. HTTP response duration is not browser page-load time, and request counts are not a human audience estimate.
Loki + Alloy — Configured and locally checked
Provides: Collects logs from explicitly labelled containers, maps Traefik routes to sites and removes query strings before Loki ingestion. Log retention is seven days.
Requirements and limits
Docker API access, labels and storage. Alloy is a trusted host-level collector: a read-only socket mount does not restrict Docker API methods. Raw Docker logs can still contain query strings; age-based retention is not a hard disk quota.
Blackbox Exporter + Node Exporter — Configured and locally checked
Provides: Page and API checks every 30 seconds through internal Traefik, plus host CPU, memory and filesystem metrics.
Requirements and limits
Registered probe targets and host metric access. Checks originate on the same server and do not prove public DNS/network reachability. Host resources are shared across workloads.
Node.js and GraphQL instrumentation — Implemented
Provides: Process metrics, event-loop measurements, structured events and client/server GraphQL error counters, including errors returned with HTTP 200.
Requirements and limits
The Prometheus client and a configured separate metrics listener. Metrics are not mounted on the public Express app. This does not report browser JavaScript errors.
Alertmanager — Configured; notification channels optional
Provides: Groups alerts and recovery events. Optional email and Telegram delivery was exercised against isolated local fixtures.
Requirements and limits
Generated configuration and channel credentials. Real provider authentication and recipient delivery need their own checks. Channels are disabled until configured.
GEO-friendly access and selective protection — Strategy defined; filtering and classification open
Provides: Two requirements: serve legitimate requests efficiently at high volume, and welcome AI systems and other bots to public content while rejecting clearly malicious requests before application work. Monitoring supplies evidence for the owner’s local policy.
Requirements and limits
Representative capacity measurements, site-specific rules and a chosen enforcement mechanism. Useful automation, rejected abuse and uncertain traffic need separate accounting. Current graphs include all traffic; no blocker or classifier is implemented, and GEO gains have not been measured. Public robots.txt currently allows crawling, which does not guarantee indexing or AI citations.
Request/cache measurement solution — Implementation open
Provides: Would quantify Varnish cache hits, misses and origin work over time. HTTP integration tests already check selected cache behavior; Traefik traffic graphs alone do not provide this breakdown.
Requirements and limits
Varnish-specific counters or another verified source, plus an observation window. Dedicated cache-hit/origin-work monitoring remains open alongside the implemented request metrics.
Future branches — technology choices still open
These remain requirement areas until a concrete solution is selected. They do not form a mandatory sequence of additions.
Persistent storage — Open
Provides: Durable shared data where needed.
Requirements and limits
A data model, access boundaries, backups and migrations. No database has been selected; an API does not automatically require a database.
Typed API/data contracts — Open
Provides: Pothos already provides a typed server schema. Generated frontend operations, an API client and end-to-end data contracts remain open.
Requirements and limits
A real frontend data interaction and a chosen client/code-generation approach, plus runtime validation where needed.
Payments and transactions — Open
Provides: Transactional workflows when a real product requirement calls for them.
Requirements and limits
A business flow, provider, trusted processing, durable state and recovery. No payment technology has been selected.
Formal solution composition — Open
Provides: Could check solution compatibility and dependency obligations automatically.
Requirements and limits
A useful schema and enough complexity to justify maintenance. This list does not require a runtime framework or graph database.
Есть вопросы о поддержке сайта?
Здесь появится чат с моим ИИ-помощником. Вы сможете задать свои вопросы, разобраться в условиях и обсудить, подходит ли вам поддержка сайта.
Чат пока не подключён.