How ns-engineering-geotechnical-services/nswebsite works
1. Overall shape
This repository is a static Next.js 16 site for NS Engineering & Geotechnical Services. The architecture is centered on prebuilt pages, content generation scripts, and static deployment, not a long-running backend. The main runtime output is an exported site served from GitHub Pages.
2. Primary data layer: content-first, file-based
Most site content lives in the content/ directory as CSV-based source data organized by domain: projects, services, FAQ, team, alumni, eLibrary, homepage hero, categories, company info, and rotating metrics. These files are the canonical content store for the site and are versioned in Git.
3. Content ingestion pipeline
The scripts/ folder is the main build-time data pipeline. scripts/build-content.ts orchestrates parsers that transform CSV and Google Sheets data into generated artifacts. The parsers under scripts/parsers/ handle each content domain separately, including Google Sheets import, CSV export, SEO generation, media validation, and R2-related path handling.
4. Dual source-of-truth mode
The site supports two content workflows: local CSV mode and cloud Google Sheets mode. Local mode reads the committed CSVs directly; cloud mode pulls from Sheets and can export back to CSV. This is an important architectural boundary because the app itself only consumes the generated/static content, while the build pipeline decides where that content comes from.
5. Media boundary and asset storage
Rich media is stored as static assets under content/.../images and public/, with additional workflow support for syncing media through Google Drive → Cloudflare R2 via rclone. CSV content stays in Git, while heavy binary assets are treated as a separate distribution concern. That split affects how pages resolve image and PDF URLs.
6. Application layer: App Router pages plus client islands
src/app/ contains the route structure for the site: home, about, projects, services, eLibrary, FAQ, careers, team, alumni, contact, privacy, and terms. Most routes have a page.tsx server component and a matching *Client.tsx client component for interaction-heavy UI. This keeps page composition server-rendered while isolating search, modals, maps, accordions, and forms to client-side islands.
7. Reusable UI and feature subsystems
src/components/ is organized by feature rather than by primitive UI only. There are dedicated subsystems for home sections, projects, services, eLibrary, FAQ, careers, team, alumni, layout, map, SEO, and animations. Shared building blocks like buttons, cards, modals, inputs, carousels, and toasts are in src/components/ui/ and are reused across feature areas.
8. High-interactivity domains
The most interactive parts of the site are the project portfolio, interactive map, eLibrary, FAQ accordion, careers portal, and contact/RFQ forms. These features rely on client components, modal dialogs, search/filter UIs, and in the case of the map, a Leaflet-based geospatial layer with markers and popups. That makes them the main boundaries where static rendering gives way to client behavior.
9. SEO and structured data as a first-class layer
SEO is not an afterthought here; it has its own src/components/seo/ and src/lib/seo/ subsystems. The repo generates page metadata and JSON-LD schemas for organization, local business, projects, services, FAQ, and technical terminology. This indicates the site is designed to be machine-readable for search engines and AI crawlers, not just visually presentable.
10. Shared domain models and typed contracts
src/types/ defines the data contracts for each content domain, while src/data/ contains higher-level site data such as careers, redirects, and site config. This separation keeps content parsing, page rendering, and schema generation aligned on the same typed structures.
11. Deployment and publishing flow
The production path is GitHub Actions-driven. Workflow files under .github/workflows/ handle dev deployment, production deployment, and manual sync. The README indicates the deploy branch is cloudflare, and the pipeline also performs media sync, CSV export, build, and GitHub Pages publishing. So deployment is a build-and-publish pipeline, not a server rollout.
12. Navigation, redirects, and legacy migration
The repo includes explicit support for URL migration from old WordPress paths to the new route structure. Scripts generate redirect pages and sitemap artifacts, and the public/ directory contains legacy-friendly entry points like /career/, /downloads/, and /gallery/ as part of the migration strategy. This is important for architecture because URL continuity is treated as a compatibility layer.
13. Operational boundary: forms and external services
The contact and careers areas imply integration points for email or submission handling, with src/lib/emailService.ts acting as the service boundary. The repo does not appear to run a custom backend; instead, any outbound workflow is handled through client-side form interactions or build-time generation plus external services.
14. What an architecture diagram should emphasize
A correct diagram should show: content sources (CSV/Google Sheets/media) feeding a build-time parser pipeline, producing typed generated data and static assets, which are then consumed by a Next.js static site with client-side feature islands, enriched by SEO/schema generation, and published through GitHub Actions to GitHub Pages/CDN-backed media storage.
Main entry points: build-content.ts Content build · app App routes · content CSV content · data-source.ts Source modes
Components 21
Content sources
Versioned CSV content, media, and legacy static assets that feed the site.
- CSV content · Canonical domain content stored as CSV files under content/ for projects, services, FAQ, team, alumni, eLibrary, homepage, company info, and metrics.
content - Media assets · Images and PDFs stored alongside content and in public/ for site pages and downloadable assets.
content/projects - Public assets · Prebuilt compatibility pages and site assets served directly from public/.
public
Build pipeline
Scripts that ingest, normalize, validate, and export content at build time.
- Content build · Main build-time entry point that coordinates content generation.
scripts/build-content.ts - Source modes · Selects between local CSV mode and Google Sheets mode as the content source boundary.
scripts/parsers/data-source.ts - CSV ingest · Parses committed CSV content into typed records.
scripts/parsers/csv-parser.ts - Sheets sync · Imports content from Google Sheets and supports export back to CSV.
scripts/parsers/google-sheets-parser.ts - Domain parsers · Per-domain parsers for projects, services, FAQ, team, alumni, eLibrary, hero, milestones, company info, categories, and rotating metrics.
scripts/parsers/project-parser.ts - Media checks · Validates media references and handles R2-oriented path and asset workflow concerns.
scripts/parsers/validate-media.ts - SEO generator · Builds metadata and structured data artifacts during content generation.
scripts/parsers/seo-generator.ts
Next.js app
App Router pages and client-side feature islands for the static site.
- App routes · Static App Router pages for home, about, projects, services, eLibrary, FAQ, careers, team, alumni, contact, privacy, and terms.
src/app - Client islands · Interactive route-specific client components for search, filters, dialogs, maps, forms, and accordions.
src/app/projects/ProjectsClient.tsx - Home sections · Hero, timeline, featured content, services, and rotating metrics sections for the landing page.
src/components/home - Feature modules · Domain feature components for projects, services, eLibrary, FAQ, careers, alumni, team, and map views.
src/components/projects
Shared subsystems
Reusable UI, SEO, data, and type layers used across pages and generators.
- UI primitives · Reusable buttons, cards, modals, inputs, textareas, carousels, and toasts.
src/components/ui - SEO layer · Metadata helpers and JSON-LD components for organization, local business, projects, services, and FAQ schemas.
src/lib/seo - Site data · Higher-level typed data for careers, projects, redirects, site config, and technical terms.
src/data - Type contracts · Typed models that keep content parsing, page rendering, and schema generation aligned.
src/types - Email service · Service boundary for outbound contact and careers workflows.
src/lib/emailService.ts
Delivery
Static publishing, redirects, and deployment automation.
- GitHub Actions · Workflows that build, sync, and publish the static site.
.github/workflows/deploy.yml - Redirects · Generated and legacy URL continuity for migrated WordPress-style paths and sitemap/robots outputs.
scripts/generate-redirects.ts
Connections 24
- CSV content → CSV ingest: reads · Build uses committed CSV content as the local source of truth.
- CSV content → Source modes: selects · Local vs cloud mode decision starts from content source selection.
- Sheets sync → Source modes: selects · Cloud mode routes through Google Sheets ingestion.
- Source modes → Content build: feeds · The orchestrator chooses the active source mode before parsing.
- CSV ingest → Content build: feeds · Parsed CSV records flow into the content build.
- Sheets sync → Content build: feeds · Sheets-derived data is normalized by the build orchestrator.
- Domain parsers → Content build: runs in · Domain-specific transformers are coordinated by the build entry point.
- Media assets → Media checks: validates · Media references and asset paths are checked during generation.
- Media checks → Content build: feeds · Validated media state informs generated content artifacts.
- SEO generator → Content build: emits · Metadata and structured data are generated alongside content.
- CSV content → Domain parsers: domain input · Each content domain is parsed from its own CSV sources.
- App routes → Client islands: renders · Route-level pages compose interactive client components where needed.
- App routes → Home sections: uses · The home route is built from reusable landing-page sections.
- App routes → Feature modules: uses · Feature routes compose their domain subsystems from shared feature modules.
- Home sections → UI primitives: uses · Home sections reuse common UI primitives.
- Feature modules → UI primitives: uses · Feature components are built on the shared design system.
- App routes → SEO layer: decorated by · Pages are enriched with metadata and schema generation.
- SEO layer → Site data: maps from · Schema and metadata helpers consume higher-level site data.
- Site data → Type contracts: typed by · Shared runtime data follows the domain models.
- Content build → App routes: produces · Generated static content is consumed by the app routes.
- GitHub Actions → Public assets: publishes · GitHub Actions publishes the exported site and compatibility assets.
- Redirects → Public assets: serves · Legacy entry points and generated redirects are exposed from public/.
- Redirects → GitHub Actions: included in · Redirect generation is part of the publish pipeline.
- Email service → Client islands: used by · Contact and careers interactions route through the email boundary.