feat: production-ready Angular 21 SSR architecture with modern Node 24+ requirements

Author: janfess

.dockerignore

@@ -0,0 +1,32 @@
+# Exclude node_modules (re-installed during build)
+node_modules/
+
+# Exclude build output
+dist/
+.angular/
+.husky
+
+# Exclude git metadata
+.git/
+
+# Exclude log files
+*-dev.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Exclude editor and OS specific files
+.DS_Store
+.idea/
+.vscode/
+
+# Exclude docker files
+Dockerfile
+.dockerignore
+
+# Exclude environment files if they contain secrets (following security rules)
+# .env.local
+# .env.*.local
+# .env.development.local
+# .env.test.local
+# .env.production.local

.editorconfig

@@ -0,0 +1,16 @@
+# Editor configuration, see https://editorconfig.org
+root = true
+
+[*]
+charset = utf-8
+indent_style = space
+indent_size = 2
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.ts]
+quote_type = single
+
+[*.md]
+max_line_length = off
+trim_trailing_whitespace = false

.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI Build & Test
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        node-version: [24.x]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Use Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v4
+      with:
+        node-version: ${{ matrix.node-version }}
+        cache: 'npm'
+        
+    - name: Install dependencies
+      run: npm ci
+      
+    - name: Run Tests (Headless)
+      run: npm run test -- --watch=false --browsers=ChromeHeadless
+      
+    - name: Run Angular Build (Production + SSR)
+      run: npm run build:prod
+      
+    - name: Verify Build Artifacts
+      run: |
+        if [ ! -d "dist/personal-website/browser" ]; then
+          echo "Build failed: Browser bundle missing"
+          exit 1
+        fi
+        if [ ! -d "dist/personal-website/server" ]; then
+          echo "Build failed: Server bundle missing"
+          exit 1
+        fi
+        echo "Build succeeded. Artifacts verified."

.gitignore

@@ -0,0 +1,49 @@
+# See http://help.github.com/ignore-files/ for more about ignoring files.
+
+# Compiled output
+/dist
+/tmp
+/out-tsc
+/bazel-out
+
+# Node
+/node_modules
+/backend/node_modules
+Procfile
+/backend/Procfile
+**/*.zip
+npm-debug.log
+yarn-error.log
+/frontend-dev.log
+/backend-dev.log
+
+# IDEs and editors
+.idea/
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# Visual Studio Code
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+.history/*
+
+# Miscellaneous
+/.angular/cache
+.sass-cache/
+/connect.lock
+/coverage
+/libpeerconnection.log
+testem.log
+/typings
+
+# System files
+.DS_Store
+Thumbs.db
+.env

.husky/pre-push

@@ -0,0 +1 @@
+npm audit fix && npm test

.nvmrc

@@ -0,0 +1 @@
+24

CONTRIBUTING.md

@@ -0,0 +1,27 @@
+# Contributing to the Senior Angular Showcase
+
+Thank you for your interest in this project! As a showcase of senior-level Angular architecture, we maintain high standards for code quality and structural integrity.
+
+## 📜 Principles
+
+- **Architecture First**: All changes must adhere to the Core/Shared/Layout/Feature hierarchy.
+- **Standalone Only**: No `NgModules` are allowed.
+- **Performance Budget**: Avoid adding heavy third-party dependencies. Prioritize native Angular or lightweight custom implementations.
+- **Strict Typing**: No `any`. Use strict TypeScript types and interfaces.
+
+## 🛠️ Development Workflow
+
+1.  **Fork & Clone**: Create your own branch from `main`.
+2.  **Architecture Check**: Ensure new components are placed in the correct feature or shared directory.
+3.  **Local Testing**: Run `npm run start` and verify changes in the browser.
+4.  **Production Validation**: Run `npm run build:prod` to ensure hydration and SSR compatibility.
+
+## 🎨 Styling Guidelines
+
+- Use **Primeflex** for layout utilities.
+- Use **PrimeNG** for complex UI components (configured with Ripple: disabled).
+- Maintain the **Glassmorphism** aesthetic where applicable.
+
+---
+
+*This project is primarily a portfolio, but constructive feedback or architecture-improving PRs are always welcome.*

Dockerfile

@@ -0,0 +1,28 @@
+FROM node:24-alpine AS builder
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build:prod
+
+RUN find ./dist -name "*.map" -type f -delete
+
+FROM node:24-alpine
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+COPY --from=builder /app/dist/personal-website ./dist/personal-website
+COPY server.static.mjs ./
+
+USER node
+
+ENV PORT=8080
+EXPOSE 8080
+
+CMD ["node", "server.static.mjs"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Janfess
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,126 @@
+# Enterprise Angular 21 SSR Reference Architecture
+
+> **A production-ready, highly optimized Angular architecture designed for scale, performance, and maintainability.**
+
+This repository serves as a masterclass in modern Angular development. Engineered from the ground up by a Senior Angular Architect, it demonstrates how to architect a state-of-the-art (SOTA) frontend application using the absolute latest features of Angular 21. It is explicitly designed to serve as a technical reference for enterprise teams and prospective clients.
+
+## 🚀 Why This Architecture is "Senior-Level"
+
+Unlike typical frontend portfolios, this project treats the UI as a comprehensive, production-critical system:
+
+- **Enterprise Feature-Driven Design:** The codebase strictly adheres to the `Core` / `Shared` / `Feature` / `Layout` module pattern. This eliminates circular dependencies, enforces a clean separation of concerns, and ensures the codebase remains maintainable as it scales.
+- **Aggressive Performance Optimization:** Utilizes intelligent asset preloading, HTTP `Link` headers, intersection observers for lazy loading, and advanced `@defer` blocks. The result is a near-instant First Contentful Paint (FCP) and exceptional Core Web Vitals.
+- **Node.js Express SSR & SSG Mastery:** Bypasses basic routing with a custom Express `server.ts` that handles dynamic `Accept-Language` locale detection, aggressive static asset caching (`Cache-Control`), security headers, and prerendering (SSG) for unparalleled SEO performance.
+- **Production-Grade DevOps & Automation:** Features an automated GitHub Actions CI/CD pipeline, strict TypeScript compilation enforcement, and Husky git hooks. 
+- **Modern UI/UX Standards:** Built with PrimeNG 21 (Aura theme) and PrimeFlex, demonstrating deep expertise in integrating complex, enterprise-grade UI libraries cleanly into a modern Angular context.
+- **PWA & Offline Resilience:** Fully configured Service Worker with custom background update broadcasting (`sw-update-broadcast.service.ts`) for seamless, zero-downtime client updates.
+- **Decoupled Data Architecture:** Implements a strict Service Layer pattern for all HTTP interactions. Components are kept "lean" and unaware of API implementation details, while `InquiryService` handles data mutation, error catching, and state persistence via RxJS Observables.
+
+
+### System Architecture Flow
+
+```mermaid
+graph TD
+    Client[Client Browser] -->|HTTP Request| Express[Node.js Express Server]
+    Express -->|Static Asset?| Static[Serve /browser files]
+    Express -->|Dynamic Route?| Locale[Detect Locale via Headers/URL]
+    Locale --> AngularEngine[Angular Node App Engine]
+    AngularEngine -->|Prerendered?| SSG[Serve SSG HTML]
+    AngularEngine -->|Dynamic?| SSR[Render Angular Component]
+    SSR --> Express
+    SSG --> Express
+    Express -->|Response| Client
+```
+
+### Data Interaction Flow (Reactive Pattern)
+
+```mermaid
+graph LR
+    View[Component Template] -->|User Action| Comp[Angular Component]
+    Comp -->|Form Data| Service[InquiryService / Core]
+    Service -->|HTTP POST| API[Backend API / Cloudflare]
+    API -->|Response| Service
+    Service -->|Observable| Comp
+    Comp -->|Update UI| View
+```
+
+### Component Structure
+
+```mermaid
+graph TD
+    App[AppRoot Component] --> Layout
+    App --> RouterOutlet
+    
+    Layout --> Header[Header Component]
+    Layout --> Footer[Footer Component]
+    
+    RouterOutlet --> Features
+    
+    Features --> Home[Home Module]
+    Features --> About[About Module]
+    Features --> Legal[Legal Module]
+    Features --> Prep[Prep Module]
+    
+    Home --> SharedComponents
+    About --> SharedComponents
+    Legal --> SharedComponents
+    
+    subgraph Shared
+    SharedComponents[Buttons, Breadcrumbs, Schedulers]
+    end
+    
+    subgraph Core
+    Services[SEO, SW Updates, Inquiry Handling, Layout Adjusters]
+    end
+    
+    Features -.->|Injects| Core
+```
+
+## Project Structure
+
+```
+src/
+├── app/
+│   ├── core/         # Singleton services (SEO, Updates, Inquiry, Adjustments)
+│   ├── features/     # Feature modules (Home, About, Legal, etc.)
+│   ├── layout/       # Global structural components (Header, Footer)
+│   └── shared/       # Reusable UI components and utilities
+├── assets/           # Static assets, fonts, icons
+├── environments/     # Environment-specific configuration
+└── locale/           # i18n translation files
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js (v24 or higher recommended)
+- Angular CLI
+
+### Installation
+
+1. Clone the repository:
+   ```bash
+   git clone <your-repo-url>
+   cd personal-website-opensource
+   ```
+
+2. Install dependencies:
+   ```bash
+   npm install
+   ```
+
+3. Configure Environment Variables:
+   Update `src/environments/environment.ts` with your specific API and Worker URLs if you are connecting to a backend.
+
+### Development Server
+
+Run `npm run start` (or `ng serve`) for a dev server. Navigate to `http://localhost:4200/`. The application will automatically reload if you change any of the source files.
+
+### Build
+
+Run `npm run build:prod` to build the project for production. The build artifacts will be stored in the `dist/` directory. This utilizes Angular's static output mode for prerendering.
+
+## License
+
+This project is open-sourced under the MIT License.