Decyzje dostępne do wglądu.

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect, owner through autonomous delivery instruction - **Tags:** architecture, documentation ## Context and Problem Statement The website demonstrates the consultancy's engineering practice. Decisions must remain understandable after delivery and traceable to requirements. ## Decision Drivers - Transparent trade-offs and low maintenance cost. - Immutable accepted decisions with explicit supersession. ## Considered Options 1. MADR in Git. 2. External wiki. 3. Code comments alone. ## Decision Outcome **Chosen option:** MADR in Git, alongside changes. Accepted records are not rewritten; later decisions supersede them. ### Consequences - **Positive:** Reviewable history and a public engineering page. - **Negative / trade-offs:** Documentation requires maintenance. - **Risks & mitigations:** CI verifies the ADR index. ## Pros and Cons of the Options ### MADR - Pro: versioned and portable. - Con: longer than informal notes. ### Wiki / comments - Pro: convenient for immediate notes. - Con: context can drift away from implementation. ## Validation CI index parity check and engineering page build. NFR-006. ## Links - [Requirements](../REQUIREMENTS.md)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect - **Tags:** frontend, performance ## Context and Problem Statement Most content is editorial, with several stateful demonstrations. Shipping a full application runtime to every page would spend the JavaScript budget unnecessarily. ## Decision Drivers - Static accessibility and bilingual SEO. - Initial JavaScript under 100 KB gzip. - Stateful diagnostic, pipeline and form. ## Considered Options 1. Current stable Astro with React islands. 2. Next.js static export. 3. Blazor WebAssembly. ## Decision Outcome **Chosen option:** Astro 7 with strict TypeScript and React islands. This satisfies the requested Astro 5+ baseline while using current packages. Hydrate below-fold features on visibility. ### Consequences - **Positive:** Most pages contain no React runtime. - **Negative / trade-offs:** Separate island boundaries require explicit props. - **Risks & mitigations:** Test static fallbacks and enforce a built JS budget. ## Pros and Cons of the Options ### Astro - Pro: static-first MDX and selective hydration. - Con: Astro and React syntax both needed. ### Next.js - Pro: integrated application platform. - Con: unnecessary client/runtime complexity here. ### Blazor - Pro: shared C# skills. - Con: larger browser payload for a marketing site. ## Validation Build, Playwright and Lighthouse. FR-003–FR-007, NFR-001. ## Links - [Astro documentation](https://docs.astro.build/)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect - **Tags:** frontend, accessibility ## Context and Problem Statement A bilingual technical brand needs consistent contrast, spacing and motion across dark and light themes. Polish text needs flexible components. ## Decision Drivers - One token source and responsive layouts. - Keyboard and reduced-motion support. ## Considered Options 1. Tailwind v4 plus semantic CSS variables. 2. CSS-in-JS. 3. A prebuilt component theme. ## Decision Outcome **Chosen option:** Tailwind v4 with semantic CSS variables and reusable CSS classes. Native dialog/details elements provide accessible primitives; React controls stateful demonstrations. Custom CSS handles the architecture illustration. ### Consequences - **Positive:** Zero styling runtime and explicit theme tokens. - **Negative / trade-offs:** Design ownership requires careful review. - **Risks & mitigations:** axe and both-locale responsive tests. ## Pros and Cons of the Options ### Tailwind + tokens - Pro: compact compiled output and theme consistency. - Con: two styling conventions. ### CSS-in-JS / prebuilt theme - Pro: convenient component APIs. - Con: runtime or visual constraints without a benefit here. ## Validation Theme, 320px layout and focus checks. FR-002, NFR-002. ## Links - [Requirements](../REQUIREMENTS.md)

- **Status:** Superseded by ADR-0011 for current hosting - **Date:** 2026-10-23 - **Deciders:** Implementation architect - **Tags:** infra, security ## Context and Problem Statement The owner requires Azure hosting, preview environments and a .NET contact endpoint. Static content does not need an always-on web server. ## Decision Drivers - Azure ownership, HTTPS, PR previews and reproducible resources. - Separate API lifecycle and supported .NET runtime. ## Considered Options 1. Static Web Apps Standard and linked Function. 2. App Service for the entire site. 3. Container Apps. ## Decision Outcome **Chosen option:** SWA Standard with a linked isolated .NET Function. Static output deploys with GitHub Actions; a separate infrastructure workflow creates resources. Live deployment requires owner Azure configuration and is not inferred from a local build. ### Consequences - **Positive:** CDN delivery, security headers and preview URLs. - **Negative / trade-offs:** Standard tier cost and separate Function deployment. - **Risks & mitigations:** Preview forms are disabled until an explicitly configured safe preview API exists; no accidental production mail from previews. ## Pros and Cons of the Options ### SWA - Pro: fits static site and PR workflow. - Con: linked backends require Standard tier. ### App Service / Container Apps - Pro: full server control. - Con: more infrastructure for static content. ## Validation Bicep build/what-if and deployed smoke test. FR-009. ## Links - [Azure SWA documentation](https://learn.microsoft.com/azure/static-web-apps/)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect under autonomous owner instruction - **Tags:** backend, security ## Context and Problem Statement A contact endpoint handles personal data and mail. .NET 8 is close to end of support, so a new release should use a longer-lived baseline. ## Decision Drivers - Supported runtime - localised responses - abuse prevention ## Considered Options 1. Linked .NET 10 isolated Function 2. Managed SWA .NET 8 API 3. Third-party form service ## Decision Outcome **Chosen option:** Linked .NET 10 isolated Function. Use Windows Consumption with .NET 10 isolated. Verify Turnstile including hostname, enforce validation/consent/honeypot and rate-limit HMAC-hashed IP and email identities in Table Storage. Send plain-text notifications and localised acknowledgements through ACS. ### Consequences - **Positive:** Independent lifecycle and durable anti-abuse. - **Negative / trade-offs:** More infrastructure; sequential email sends can partially succeed. - **Risks & mitigations:** Default disabled. Fail closed on verification/storage errors, log no contact bodies, clean expired rate counters daily. No automatic retries after partial mail failure. ## Pros and Cons of the Options ### Linked .NET 10 isolated Function - Pro: Independent lifecycle and durable anti-abuse. - Con: More infrastructure; sequential email sends can partially succeed. ### Managed SWA .NET 8 API - Pro: Less local implementation work. - Con: Less direct fit for the chosen support, ownership or performance constraints. ### Third-party form service - Pro: Viable with different constraints. - Con: Adds unnecessary dependencies or maintenance here. ## Validation xUnit and live Azure/mail smoke test. FR-008. ## Links - [Requirements](../REQUIREMENTS.md) - [Architecture](../ARCHITECTURE.md)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect under autonomous owner instruction - **Tags:** content, frontend ## Context and Problem Statement Editorial content needs validated metadata, translation pairs and reviewable history without an external CMS. ## Decision Drivers - Portable source - build-time safety - bilingual parity ## Considered Options 1. Astro MDX and Zod 2. Headless CMS 3. Embedded component content ## Decision Outcome **Chosen option:** Astro MDX and Zod. Use services, insights and case-studies collections with paired en/pl directories and translationKey. Build fails on missing counterparts. An intentionally untranslated article must receive an explicit mapped notice route before relaxing this gate. ### Consequences - **Positive:** Reviewable content and no CMS runtime. - **Negative / trade-offs:** Git editing is needed and incomplete translation blocks publication. - **Risks & mitigations:** Validate schema and routes. Label every illustrative result. ## Pros and Cons of the Options ### Astro MDX and Zod - Pro: Reviewable content and no CMS runtime. - Con: Git editing is needed and incomplete translation blocks publication. ### Headless CMS - Pro: Less local implementation work. - Con: Less direct fit for the chosen support, ownership or performance constraints. ### Embedded component content - Pro: Viable with different constraints. - Con: Adds unnecessary dependencies or maintenance here. ## Validation Content checker and build link audit. FR-005, FR-007. ## Links - [Requirements](../REQUIREMENTS.md) - [Architecture](../ARCHITECTURE.md)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect under autonomous owner instruction - **Tags:** frontend, accessibility ## Context and Problem Statement Technical visuals need subtle motion while remaining small, readable and controllable. ## Decision Drivers - Reduced motion - keyboard support - small runtime ## Considered Options 1. CSS plus React state and native HTML 2. Motion library 3. WebGL hero ## Decision Outcome **Chosen option:** CSS plus React state and native HTML. Use SVG/CSS data flow and cursor tilt, native dialog/details and React islands. These effects do not require Motion or WebGL. Reduced-motion disables animation and smooth scroll. Pipeline has a pause control. Testimonials advance manually. Timeline uses keyboard tabs and a noscript fallback. ### Consequences - **Positive:** No animation runtime and static visual fallback. - **Negative / trade-offs:** No scroll-driven phase activation or animated metric counters in this release. - **Risks & mitigations:** Static metrics avoid layout shift; test stateful controls with keyboard and axe. ## Pros and Cons of the Options ### CSS plus React state and native HTML - Pro: No animation runtime and static visual fallback. - Con: No scroll-driven phase activation or animated metric counters in this release. ### Motion library - Pro: Less local implementation work. - Con: Less direct fit for the chosen support, ownership or performance constraints. ### WebGL hero - Pro: Viable with different constraints. - Con: Adds unnecessary dependencies or maintenance here. ## Validation Playwright and reduced-motion review. FR-002, FR-004, NFR-002. ## Links - [Requirements](../REQUIREMENTS.md) - [Architecture](../ARCHITECTURE.md)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect under autonomous owner instruction - **Tags:** privacy, security ## Context and Problem Statement The owner has not approved an analytics processor or provided controller details. The site does not need tracking to work. ## Decision Drivers - Data minimisation - no cookie banner - smaller JS ## Considered Options 1. No frontend analytics 2. Plausible 3. Browser Application Insights SDK ## Decision Outcome **Chosen option:** No frontend analytics. Load no analytics script. Use guarded localStorage only for theme/language. Function host telemetry records operational errors without submitted content; Azure IP masking is enabled. A later analytics addition requires a new ADR. ### Consequences - **Positive:** No analytics cookies or third-party analytics requests. - **Negative / trade-offs:** No visitor funnels or browser App Insights integration. - **Risks & mitigations:** Legal pages describe actual publication state. Review infrastructure telemetry retention before launch. ## Pros and Cons of the Options ### No frontend analytics - Pro: No analytics cookies or third-party analytics requests. - Con: No visitor funnels or browser App Insights integration. ### Plausible - Pro: Less local implementation work. - Con: Less direct fit for the chosen support, ownership or performance constraints. ### Browser Application Insights SDK - Pro: Viable with different constraints. - Con: Adds unnecessary dependencies or maintenance here. ## Validation Source/network review. NFR-004. ## Links - [Requirements](../REQUIREMENTS.md) - [Architecture](../ARCHITECTURE.md)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect under autonomous owner instruction - **Tags:** infra, security ## Context and Problem Statement Resources must be reproducible and changes reviewable without manually creating them in the portal. ## Decision Drivers - Azure-native - no state store - secret isolation ## Considered Options 1. Bicep 2. Terraform 3. Portal-only setup ## Decision Outcome **Chosen option:** Bicep. Provision SWA Standard, linked Windows Function, Storage, Log Analytics, App Insights, ACS and an Azure-managed email domain. Use secure parameters and Function app settings. GitHub deploys with OIDC. ### Consequences - **Positive:** Native what-if and reproducibility. - **Negative / trade-offs:** Azure-specific costs; Turnstile registration, email production limits, GitHub configuration and DNS remain owner account tasks. - **Risks & mitigations:** Default ContactEnabled=false. No invented account values. Never infer cloud success from a local build. ## Pros and Cons of the Options ### Bicep - Pro: Native what-if and reproducibility. - Con: Azure-specific costs; Turnstile registration, email production limits, GitHub configuration and DNS remain owner account tasks. ### Terraform - Pro: Less local implementation work. - Con: Less direct fit for the chosen support, ownership or performance constraints. ### Portal-only setup - Pro: Viable with different constraints. - Con: Adds unnecessary dependencies or maintenance here. ## Validation Bicep build; authenticated what-if before live use. FR-009. ## Links - [Requirements](../REQUIREMENTS.md) - [Architecture](../ARCHITECTURE.md)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Implementation architect under autonomous owner instruction - **Tags:** content, frontend ## Context and Problem Statement English and Polish need equivalent pages and localised slugs from the first release. ## Decision Drivers - Equivalent switching - professional Polish - build parity ## Considered Options 1. Central routes and typed dictionaries with paired MDX 2. Duplicated sites 3. Runtime machine translation ## Decision Outcome **Chosen option:** Central routes and typed dictionaries with paired MDX. EN lives at root and PL at /pl. Astro i18n config and route-map.json drive shared templates. Typed t() supplies UI copy. Data is bilingual. Switch links preserve route identity and anchors. Browser language is suggested without redirect. Intl formats dates, numbers and plurals. Fonts include Latin Extended. ### Consequences - **Positive:** Stable SEO and no translation runtime. - **Negative / trade-offs:** New locales require dictionary/config/schema/route/test extensions and editorial work. - **Risks & mitigations:** Parity gates, localised metadata, sitemap alternates, and both-locale browser tests. Literal copy lint has explicit technical-name exceptions and cannot replace review. ## Pros and Cons of the Options ### Central routes and typed dictionaries with paired MDX - Pro: Stable SEO and no translation runtime. - Con: New locales require dictionary/config/schema/route/test extensions and editorial work. ### Duplicated sites - Pro: Less local implementation work. - Con: Less direct fit for the chosen support, ownership or performance constraints. ### Runtime machine translation - Pro: Viable with different constraints. - Con: Adds unnecessary dependencies or maintenance here. ## Validation i18n tests, build audit, Playwright. FR-001, NFR-005. ## Links - [Requirements](../REQUIREMENTS.md) - [Architecture](../ARCHITECTURE.md)

- **Status:** Accepted - **Date:** 2026-10-23 - **Deciders:** Repository owner and implementation architect - **Tags:** infra, deployment, security - **Supersedes:** ADR-0004 for the current hosting target ## Context and Problem Statement The owner now requests the same GitHub/GHCR deployment pattern as AI-Website on the existing Ubuntu box. The clarified target is HTTP on the private address 192.168.1.5, without a public domain or Cloudflare. Company details remain deferred. ## Decision Drivers - Reuse the existing runner while keeping images, ports, bridge and manifests separate. - Deploy only tested main commits and keep repository builds off the production runner. - Preserve the bilingual static output and its generated CSP hashes. ## Considered Options 1. Continue with Azure SWA as the immediate hosting target. 2. Package static output with a minimal Node HTTP server and deploy from GHCR. 3. Add a full application server and contact backend to the Ubuntu image. ## Decision Outcome **Chosen option:** Build a multi-stage Node 24 image on GitHub-hosted runners. Publish to ghcr.io/grexiox/hill-software only after quality, browser, Lighthouse, visual and container gates pass. Deploy the exact commit tag using the existing runner with an additional hill-software label and protected hill-software-production environment. The server-side reviewed manifests bind port 5081 only to 192.168.1.5. A distinct br-hillsoft bridge, resource limits, nonroot user, read-only filesystem and no host mounts confine the container. Docker manages the bridge and published port without a custom host firewall or interactive sudo step. The container uses restart=unless-stopped and resumes after reboot. The bridge is not an outbound firewall or a VM boundary. The static server preloads and compresses public files, applies the generated CSP, serves the custom 404 and canonical directory redirects, and provides a health endpoint. LAN mode omits HSTS and upgrade-insecure-requests and sends noindex headers. Public HTTPS would require a separate reviewed configuration and rebuild with the real origin. ### Consequences - **Positive:** No Azure or custom registry secrets are needed for this LAN deployment. GitHub's job-scoped token publishes and pulls the linked GHCR package. - **Negative / trade-offs:** HTTP is intended for the trusted private network. Container bridge separation does not prohibit access to services published on the Docker host. A stricter outbound policy would need a separately reviewed host firewall. - **Risks & mitigations:** Domain metadata is baked into the image; deployment checks the image origin against the server configuration before replacing the running container. Source changes to deployment files require a separate reviewed copy to the server; the runner updates only the image. Contact defaults disabled. The image includes a private .NET contact backend that shares validation and NotificationHub integration with the optional Azure Function. Bicep and Function sources remain reference alternatives under ADR-0005/0009. Azure deployment/infrastructure workflows were removed on 2026-10-27; Ubuntu releases use hill-ci.yml, which also includes mobile Lighthouse verification. ## Validation Node HTTP server tests, frozen frontend build, actionlint, Compose model validation, Linux image build and isolated container smoke/confinement checks. A real GitHub-triggered deployment remains a separate verification after repository settings are configured. ## Links - [Deployment runbook](../DEPLOYMENT.md) - [GitHub Container Registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry)