# ns-engineering-geotechnical-services/nswebsite architecture

> Architecture diagram of the GitHub repository ns-engineering-geotechnical-services/nswebsite, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ns-engineering-geotechnical-services/nswebsite
- Repository: https://github.com/ns-engineering-geotechnical-services/nswebsite

## Overview

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: [`scripts/build-content.ts`](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/build-content.ts) (Content build), [`src/app`](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/app) (App routes), [`content`](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/content) (CSV content), [`scripts/parsers/data-source.ts`](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/data-source.ts) (Source modes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_content["Content sources"]
  node_content_csv["CSV content<br/>content source"]
  node_content_media["Media assets<br/>static media"]
  node_public_static["Public assets<br/>static output"]
end

subgraph group_group_pipeline["Build pipeline"]
  node_build_orchestrator["Content build<br/>orchestrator<br/>[build-content.ts]"]
  node_data_sources["Source modes<br/>source adapter<br/>[data-source.ts]"]
  node_csv_ingest["CSV ingest<br/>parser<br/>[csv-parser.ts]"]
  node_sheets_ingest["Sheets sync<br/>cloud sync"]
  node_domain_parsers["Domain parsers<br/>transformers<br/>[project-parser.ts]"]
  node_media_checks["Media checks<br/>validator<br/>[validate-media.ts]"]
  node_seo_gen["SEO generator<br/>schema pipeline<br/>[seo-generator.ts]"]
end

subgraph group_group_app["Next.js app"]
  node_site_routes["App routes<br/>route tree"]
  node_client_islands["Client islands<br/>interactive UI<br/>[ProjectsClient.tsx]"]
  node_home_ui["Home sections<br/>feature UI"]
  node_feature_ui["Feature modules<br/>feature UI"]
end

subgraph group_group_shared["Shared subsystems"]
  node_shared_ui["UI primitives<br/>design system"]
  node_seo_layer["SEO layer<br/>schema ui"]
  node_domain_data["Site data<br/>runtime data"]
  node_type_contracts["Type contracts<br/>domain types"]
  node_email_boundary["Email service<br/>integration boundary<br/>[emailService.ts]"]
end

subgraph group_group_delivery["Delivery"]
  node_deploy_flow["GitHub Actions<br/>deployment pipeline<br/>[deploy.yml]"]
  node_redirect_layer["Redirects<br/>migration layer"]
end

node_content_csv -->|"reads"| node_csv_ingest
node_content_csv -->|"selects"| node_data_sources
node_sheets_ingest -->|"selects"| node_data_sources
node_data_sources -->|"feeds"| node_build_orchestrator
node_csv_ingest -->|"feeds"| node_build_orchestrator
node_sheets_ingest -->|"feeds"| node_build_orchestrator
node_domain_parsers -->|"runs in"| node_build_orchestrator
node_content_media -->|"validates"| node_media_checks
node_media_checks -->|"feeds"| node_build_orchestrator
node_seo_gen -->|"emits"| node_build_orchestrator
node_content_csv -->|"domain input"| node_domain_parsers
node_site_routes -->|"renders"| node_client_islands
node_site_routes -->|"uses"| node_home_ui
node_site_routes -->|"uses"| node_feature_ui
node_home_ui -->|"uses"| node_shared_ui
node_feature_ui -->|"uses"| node_shared_ui
node_site_routes -->|"decorated by"| node_seo_layer
node_seo_layer -->|"maps from"| node_domain_data
node_domain_data -->|"typed by"| node_type_contracts
node_build_orchestrator -->|"produces"| node_site_routes
node_deploy_flow -->|"publishes"| node_public_static
node_redirect_layer -->|"serves"| node_public_static
node_redirect_layer -->|"included in"| node_deploy_flow
node_email_boundary -->|"used by"| node_client_islands

click node_content_csv "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/content"
click node_content_media "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/content/projects"
click node_public_static "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/public"
click node_build_orchestrator "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/build-content.ts"
click node_data_sources "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/data-source.ts"
click node_csv_ingest "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/csv-parser.ts"
click node_sheets_ingest "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/google-sheets-parser.ts"
click node_domain_parsers "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/project-parser.ts"
click node_media_checks "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/validate-media.ts"
click node_seo_gen "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/seo-generator.ts"
click node_site_routes "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/app"
click node_client_islands "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/src/app/projects/ProjectsClient.tsx"
click node_home_ui "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/components/home"
click node_feature_ui "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/components/projects"
click node_shared_ui "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/components/ui"
click node_seo_layer "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/lib/seo"
click node_domain_data "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/data"
click node_type_contracts "https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/types"
click node_email_boundary "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/src/lib/emailService.ts"
click node_deploy_flow "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/.github/workflows/deploy.yml"
click node_redirect_layer "https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/generate-redirects.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_content_csv,node_content_media,node_public_static toneBlue
class node_build_orchestrator,node_data_sources,node_csv_ingest,node_sheets_ingest,node_domain_parsers,node_media_checks,node_seo_gen toneAmber
class node_site_routes,node_client_islands,node_home_ui,node_feature_ui toneMint
class node_shared_ui,node_seo_layer,node_domain_data,node_type_contracts,node_email_boundary toneRose
class node_deploy_flow,node_redirect_layer toneIndigo
```

## Components

### Content sources

Versioned CSV content, media, and legacy static assets that feed the site.

- [CSV content](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/content): content source · Canonical domain content stored as CSV files under content/ for projects, services, FAQ, team, alumni, eLibrary, homepage, company info, and metrics. · `content`
- [Media assets](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/content/projects): static media · Images and PDFs stored alongside content and in public/ for site pages and downloadable assets. · `content/projects`
- [Public assets](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/public): static output · 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](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/build-content.ts): orchestrator · Main build-time entry point that coordinates content generation. · `scripts/build-content.ts`
- [Source modes](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/data-source.ts): source adapter · Selects between local CSV mode and Google Sheets mode as the content source boundary. · `scripts/parsers/data-source.ts`
- [CSV ingest](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/csv-parser.ts): parser · Parses committed CSV content into typed records. · `scripts/parsers/csv-parser.ts`
- [Sheets sync](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/google-sheets-parser.ts): cloud sync · Imports content from Google Sheets and supports export back to CSV. · `scripts/parsers/google-sheets-parser.ts`
- [Domain parsers](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/project-parser.ts): transformers · 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](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/validate-media.ts): validator · Validates media references and handles R2-oriented path and asset workflow concerns. · `scripts/parsers/validate-media.ts`
- [SEO generator](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/parsers/seo-generator.ts): schema pipeline · 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](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/app): route tree · Static App Router pages for home, about, projects, services, eLibrary, FAQ, careers, team, alumni, contact, privacy, and terms. · `src/app`
- [Client islands](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/src/app/projects/ProjectsClient.tsx): interactive UI · Interactive route-specific client components for search, filters, dialogs, maps, forms, and accordions. · `src/app/projects/ProjectsClient.tsx`
- [Home sections](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/components/home): feature UI · Hero, timeline, featured content, services, and rotating metrics sections for the landing page. · `src/components/home`
- [Feature modules](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/components/projects): feature UI · 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](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/components/ui): design system · Reusable buttons, cards, modals, inputs, textareas, carousels, and toasts. · `src/components/ui`
- [SEO layer](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/lib/seo): schema ui · Metadata helpers and JSON-LD components for organization, local business, projects, services, and FAQ schemas. · `src/lib/seo`
- [Site data](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/data): runtime data · Higher-level typed data for careers, projects, redirects, site config, and technical terms. · `src/data`
- [Type contracts](https://github.com/ns-engineering-geotechnical-services/nswebsite/tree/feature/cloudflareMigration/src/types): domain types · Typed models that keep content parsing, page rendering, and schema generation aligned. · `src/types`
- [Email service](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/src/lib/emailService.ts): integration boundary · Service boundary for outbound contact and careers workflows. · `src/lib/emailService.ts`

### Delivery

Static publishing, redirects, and deployment automation.

- [GitHub Actions](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/.github/workflows/deploy.yml): deployment pipeline · Workflows that build, sync, and publish the static site. · `.github/workflows/deploy.yml`
- [Redirects](https://github.com/ns-engineering-geotechnical-services/nswebsite/blob/feature/cloudflareMigration/scripts/generate-redirects.ts): migration layer · Generated and legacy URL continuity for migrated WordPress-style paths and sitemap/robots outputs. · `scripts/generate-redirects.ts`

## Connections

- 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.
