{"id":"698c6fe8b2aeaff1f1af0d6b","title":"2026 02 11 Ngx Ramblers Architecture","path":"how-to/technical-articles/2026-02-11-ngx-ramblers-architecture","contentMarkdown":"# 11-Feb-2026 — NGX Ramblers Architecture Overview\n\n_____\n\nThis article provides a visual tour of the NGX Ramblers platform architecture — every system, service, and integration that makes the application work. Use this as a reference when onboarding, debugging, or planning new features.\n\n## High-Level Architecture\n\nNGX Ramblers is an Angular 21 single-page application backed by a Node.js/Express API, hosted on Fly.io, with MongoDB Atlas as the primary data store. Cloudflare handles DNS, SSL, and CDN — all user traffic passes through it before reaching Fly.io.\n\n```mermaid\nflowchart LR\n USER@{ icon: \"ngx:user\", label: \"Users\", pos: \"b\", h: 48 }\n CF@{ icon: \"ngx:cloudflare\", label: \"Cloudflare DNS/CDN\", pos: \"b\", h: 48 }\n\n USER --> CF\n\n subgraph fly[\"Fly.io\"]\n FLY@{ icon: \"logos:fly-icon\", label: \"Docker Container\", pos: \"b\", h: 48 }\n ANGULAR@{ icon: \"logos:angular-icon\", label: \"Angular 21 SPA\", pos: \"b\", h: 48 }\n EXPRESS@{ icon: \"ngx:express\", label: \"Express API\", pos: \"b\", h: 48 }\n FLY --> ANGULAR\n ANGULAR --> EXPRESS\n FLY --> EXPRESS\n end\n\n CF --> FLY\n EXPRESS --> MONGO@{ icon: \"ngx:mongodb\", label: \"MongoDB Atlas\", pos: \"b\", h: 48 }\n EXPRESS --> S3@{ icon: \"ngx:aws\", label: \"AWS S3\", pos: \"b\", h: 48 }\n EXPRESS --> BREVO@{ icon: \"ngx:brevo\", label: \"Brevo\", pos: \"b\", h: 48 }\n EXPRESS --> RAMBLERS@{ icon: \"ngx:ramblers-hq\", label: \"Ramblers API\", pos: \"b\", h: 48 }\n\n style fly fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n```\n\n## Frontend Stack\n\nThe Angular frontend uses a rich set of libraries for maps, charts, galleries, and UI components.\n\n```mermaid\nflowchart LR\n SPA@{ icon: \"logos:angular-icon\", label: \"Angular 21\", pos: \"b\", h: 48 }\n\n subgraph ui[\"UI & Components\"]\n BS@{ icon: \"logos:bootstrap\", label: \"Bootstrap 5\", pos: \"b\", h: 48 }\n FA[\"FontAwesome\"]\n PRIME[\"PrimeNG\"]\n end\n\n subgraph maps[\"Maps\"]\n LEAF@{ icon: \"logos:leaflet\", label: \"Leaflet\", pos: \"b\", h: 48 }\n GMAP@{ icon: \"logos:google-maps\", label: \"Google Maps\", pos: \"b\", h: 48 }\n OS@{ icon: \"ngx:os-maps\", label: \"OS Maps\", pos: \"b\", h: 48 }\n end\n\n subgraph media[\"Media & Content\"]\n GALLERY[\"ng-gallery\"]\n CHARTS[\"Chart.js\"]\n MD[\"ngx-markdown\"]\n MERMAID[\"Mermaid\"]\n end\n\n subgraph analytics[\"Analytics & Security\"]\n GA@{ icon: \"logos:google-analytics\", label: \"Google Analytics\", pos: \"b\", h: 48 }\n RECAP@{ icon: \"logos:recaptcha\", label: \"reCAPTCHA\", pos: \"b\", h: 48 }\n end\n\n SPA --> ui\n SPA --> maps\n SPA --> media\n SPA --> analytics\n\n style ui fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n style maps fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n style media fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n style analytics fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n```\n\n## Backend Integrations\n\nThe Express API server connects to external services for data storage, email, DNS, event management, and walk data.\n\n```mermaid\nflowchart LR\n API@{ icon: \"ngx:express\", label: \"Express API\", pos: \"b\", h: 48 }\n\n subgraph storage[\"Storage\"]\n MONGO@{ icon: \"ngx:mongodb\", label: \"MongoDB Atlas\", pos: \"b\", h: 48 }\n S3@{ icon: \"ngx:aws\", label: \"AWS S3\", pos: \"b\", h: 48 }\n end\n\n subgraph email[\"Email\"]\n BREVO@{ icon: \"ngx:brevo\", label: \"Brevo (send)\", pos: \"b\", h: 48 }\n GMAIL@{ icon: \"logos:google-gmail\", label: \"Gmail API (inbox)\", pos: \"b\", h: 48 }\n PUBSUB@{ icon: \"logos:google-cloud\", label: \"Google Cloud Pub/Sub\", pos: \"b\", h: 48 }\n MAILCHIMP@{ icon: \"ngx:mailchimp\", label: \"Mailchimp (legacy)\", pos: \"b\", h: 48 }\n end\n\n subgraph dns[\"DNS & Hosting\"]\n CF@{ icon: \"ngx:cloudflare\", label: \"Cloudflare\", pos: \"b\", h: 48 }\n FLY@{ icon: \"logos:fly-icon\", label: \"Fly.io\", pos: \"b\", h: 48 }\n end\n\n subgraph walks[\"Walks & Events\"]\n RAMBLERS@{ icon: \"ngx:ramblers-hq\", label: \"Ramblers API\", pos: \"b\", h: 48 }\n MEETUP@{ icon: \"ngx:meetup\", label: \"Meetup API\", pos: \"b\", h: 48 }\n end\n\n subgraph geo[\"Geolocation\"]\n GMAP@{ icon: \"logos:google-maps\", label: \"Google Places\", pos: \"b\", h: 48 }\n POSTCODE[\"Postcode Lookup\"]\n OSMAP@{ icon: \"ngx:os-maps\", label: \"OS Maps Proxy\", pos: \"b\", h: 48 }\n end\n\n API --> storage\n API --> email\n API --> dns\n API --> walks\n API --> geo\n\n style storage fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n style email fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n style dns fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n style walks fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n style geo fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n```\n\n## CI/CD Pipeline\n\nCode flows from GitHub through automated builds and tests, then deploys to Fly.io with secrets imported from a secure store.\n\n```mermaid\nflowchart LR\n DEV@{ icon: \"logos:github-icon\", label: \"Push to main\", pos: \"b\", h: 48 }\n GHA@{ icon: \"logos:github-actions\", label: \"GitHub Actions\", pos: \"b\", h: 48 }\n BUILD@{ icon: \"logos:docker-icon\", label: \"Docker Build\", pos: \"b\", h: 48 }\n TEST@{ icon: \"logos:typescript-icon\", label: \"Lint & Test\", pos: \"b\", h: 48 }\n SECRETS@{ icon: \"ngx:mongodb\", label: \"Import Secrets\", pos: \"b\", h: 48 }\n DEPLOY@{ icon: \"logos:fly-icon\", label: \"Deploy to Fly.io\", pos: \"b\", h: 48 }\n\n DEV --> GHA\n GHA --> TEST\n TEST --> BUILD\n BUILD --> SECRETS\n SECRETS --> DEPLOY\n```\n\n\n\n## Data Flow: Walk Publishing\n\nWhen a walk leader creates a walk, data flows through multiple systems to reach all audiences.\n\n```mermaid\nflowchart LR\n LEADER@{ icon: \"ngx:user\", label: \"Walk Leader\", pos: \"b\", h: 48 }\n APP@{ icon: \"ngx:ramblers\", label: \"NGX Ramblers\", pos: \"b\", h: 48 }\n DB@{ icon: \"ngx:mongodb\", label: \"MongoDB\", pos: \"b\", h: 48 }\n RAPI@{ icon: \"ngx:ramblers-hq\", label: \"Ramblers API\", pos: \"b\", h: 48 }\n MEETUP@{ icon: \"ngx:meetup\", label: \"Meetup\", pos: \"b\", h: 48 }\n NOTIFY@{ icon: \"ngx:brevo\", label: \"Email Notification\", pos: \"b\", h: 48 }\n\n LEADER -->|\"Create walk\"| APP\n APP -->|\"Save\"| DB\n APP -->|\"Upload\"| RAPI\n APP -->|\"Publish\"| MEETUP\n DB -->|\"Trigger\"| NOTIFY\n```\n\n## Email Architecture\n\nNGX Ramblers now handles email in **both directions**. Brevo and Cloudflare cover outbound sending and domain routing, and a built-in **Gmail inbox** brings inbound committee mail into the application itself — with browser push notifications the moment something arrives.\n\n### Outbound: sending\n\nOutbound mail goes through **Brevo**. The unified email composer builds a message — WYSIWYG body, merge fields, recipient selection — and sends it either as a Brevo campaign (bulk) or, increasingly, as a server-side **transactional batch** job. Cloudflare email-routing rules and DNS records (SPF / DKIM / DMARC) keep delivery trustworthy.\n\n```mermaid\nflowchart LR\n COMPOSER@{ icon: \"ngx:ramblers\", label: \"Email Composer\", pos: \"b\", h: 48 }\n BREVO@{ icon: \"ngx:brevo\", label: \"Brevo API\", pos: \"b\", h: 48 }\n DELIVER@{ icon: \"ngx:user\", label: \"Recipient Inbox\", pos: \"b\", h: 48 }\n\n COMPOSER -->|\"campaign or transactional batch\"| BREVO\n BREVO --> DELIVER\n\n CF@{ icon: \"ngx:cloudflare\", label: \"Cloudflare\", pos: \"b\", h: 48 }\n CF -->|\"DNS: SPF / DKIM / DMARC\"| DELIVER\n```\n\n### Inbound: the Gmail inbox\n\nCommittee role addresses (secretary@, membership@, and so on) are routed by **Cloudflare** into a dedicated **Gmail** mailbox, which NGX reads through the **Gmail API** over OAuth — so committee mail is handled inside the app rather than forwarded to someone's personal mail client. Messages reach the app two ways:\n\n- **Watch mode** — Gmail publishes a change notification to **Google Cloud Pub/Sub**, which pushes it straight to the application. Near real-time.\n- **Poll mode** — the application periodically asks Gmail for the history delta since it last looked. A dependable fallback where Pub/Sub is not set up.\n\nEither way, each message is fetched, grouped into a thread, matched to the committee **role** it was addressed to, and stored in MongoDB (`inboxMailboxConnections`, `inboxThreads`, `inboxMessages`). The member assigned to that role reads and replies inside the app; replies go back out through the Brevo transactional path and are written back into the Gmail thread, so the mailbox stays consistent whether it is read in NGX or in Gmail.\n\n```mermaid\nflowchart TB\n SENDER@{ icon: \"ngx:user\", label: \"External sender\", pos: \"b\", h: 48 }\n CF@{ icon: \"ngx:cloudflare\", label: \"Cloudflare routing\", pos: \"b\", h: 48 }\n GMAIL@{ icon: \"logos:google-gmail\", label: \"Dedicated Gmail mailbox\", pos: \"b\", h: 48 }\n PUBSUB@{ icon: \"logos:google-cloud\", label: \"Google Cloud Pub/Sub\", pos: \"b\", h: 48 }\n APP@{ icon: \"ngx:ramblers\", label: \"NGX Ramblers\", pos: \"b\", h: 48 }\n DB@{ icon: \"ngx:mongodb\", label: \"threads + messages\", pos: \"b\", h: 48 }\n ROLE@{ icon: \"ngx:user\", label: \"Committee role\", pos: \"b\", h: 48 }\n\n SENDER -->|\"role address\"| CF\n CF -->|\"forward\"| GMAIL\n GMAIL -->|\"watch\"| PUBSUB\n PUBSUB -->|\"push\"| APP\n GMAIL -->|\"poll: history delta\"| APP\n APP -->|\"fetch · thread · route\"| DB\n DB --> ROLE\n ROLE -->|\"reply via Brevo + writeback\"| GMAIL\n```\n\n\n\n### Live notifications\n\nWhen an inbound message is stored, every member assigned to that role gets a **browser push notification** through a **service worker** and the **Web Push (VAPID)** protocol — no mail client open, no polling. The same signal drives the live unread badge in the admin UI.\n\n```mermaid\nflowchart LR\n NEW[\"New inbound message\"]\n APP@{ icon: \"ngx:ramblers\", label: \"NGX Ramblers\", pos: \"b\", h: 48 }\n SW[\"Service Worker
Web Push · VAPID\"]\n MEMBER@{ icon: \"ngx:user\", label: \"Assigned member\", pos: \"b\", h: 48 }\n\n NEW --> APP\n APP -->|\"push to subscribers\"| SW\n SW -->|\"notification + unread badge\"| MEMBER\n```\n\n\n\n### One inbox, many providers\n\nThe reader sits behind a provider interface (`InboxReaderProvider`). Gmail (`gmail-api`) is the implementation running in production today; the same interface leaves room for IMAP and other inbound sources (`brevo-inbound-parse`, `cloudflare-ingress`) without changing how threads, routing or notifications work.\n\n## File & Image Storage\n\nUser-uploaded images pass through server-side processing before reaching S3.\n\n```mermaid\nflowchart LR\n UPLOAD@{ icon: \"logos:angular-icon\", label: \"Upload from UI\", pos: \"b\", h: 48 }\n PROCESS@{ icon: \"logos:nodejs-icon\", label: \"Resize (Sharp)\", pos: \"b\", h: 48 }\n STORE@{ icon: \"ngx:aws\", label: \"AWS S3\", pos: \"b\", h: 48 }\n SERVE@{ icon: \"ngx:user\", label: \"Serve to browser\", pos: \"b\", h: 48 }\n\n UPLOAD --> PROCESS --> STORE --> SERVE\n```\n\n\n\n## Maps & Geolocation\n\nMultiple mapping services work together to provide rich location features.\n\n```mermaid\nflowchart TD\n LEAF@{ icon: \"logos:leaflet\", label: \"Leaflet\", pos: \"b\", h: 48 }\n\n subgraph tiles[\"Tile Layers\"]\n OSM@{ icon: \"logos:openstreetmap\", label: \"OpenStreetMap\", pos: \"b\", h: 48 }\n OSMAP@{ icon: \"ngx:os-maps\", label: \"OS Maps (UK)\", pos: \"b\", h: 48 }\n end\n\n subgraph search[\"Location Search\"]\n GMAP@{ icon: \"logos:google-maps\", label: \"Google Places\", pos: \"b\", h: 48 }\n POST[\"Postcode Lookup\"]\n ORS[\"OpenRouteService\"]\n end\n\n LEAF --> tiles\n LEAF --> search\n\n style tiles fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n style search fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n```\n\n## Authentication & Security\n\nThe application uses JWT for API authentication, with bcrypt for password storage and reCAPTCHA for public forms.\n\n```mermaid\nflowchart LR\n LOGIN@{ icon: \"ngx:user\", label: \"Login\", pos: \"b\", h: 48 }\n AUTH[\"Passport.js + JWT\"]\n HASH[\"bcrypt\"]\n DB@{ icon: \"ngx:mongodb\", label: \"Member Record\", pos: \"b\", h: 48 }\n RECAP@{ icon: \"logos:recaptcha\", label: \"reCAPTCHA v3\", pos: \"b\", h: 48 }\n CONTACT@{ icon: \"ngx:user\", label: \"Contact Form\", pos: \"b\", h: 48 }\n\n LOGIN --> AUTH --> DB\n AUTH --> HASH\n CONTACT --> RECAP\n```\n\n\n\n## System Configuration\n\nAll external service credentials and feature flags are stored centrally in MongoDB under the `config` collection.\n\n```mermaid\nflowchart TD\n CONFIG@{ icon: \"ngx:mongodb\", label: \"Config Collection\", pos: \"b\", h: 48 }\n\n CONFIG --> K1@{ icon: \"ngx:aws\", label: \"AWS\", pos: \"b\", h: 48 }\n CONFIG --> K2@{ icon: \"ngx:cloudflare\", label: \"Cloudflare\", pos: \"b\", h: 48 }\n CONFIG --> K3@{ icon: \"ngx:brevo\", label: \"Brevo\", pos: \"b\", h: 48 }\n CONFIG --> K4@{ icon: \"logos:google-maps\", label: \"Google Maps\", pos: \"b\", h: 48 }\n CONFIG --> K5@{ icon: \"logos:recaptcha\", label: \"reCAPTCHA\", pos: \"b\", h: 48 }\n CONFIG --> K6@{ icon: \"ngx:meetup\", label: \"Meetup\", pos: \"b\", h: 48 }\n CONFIG --> K7@{ icon: \"ngx:ramblers-hq\", label: \"Ramblers API\", pos: \"b\", h: 48 }\n CONFIG --> K8@{ icon: \"logos:google-analytics\", label: \"Google Analytics\", pos: \"b\", h: 48 }\n CONFIG --> K9@{ icon: \"logos:google-gmail\", label: \"Gmail OAuth (inbox)\", pos: \"b\", h: 48 }\n CONFIG --> K10@{ icon: \"logos:google-cloud\", label: \"Google Cloud Pub/Sub\", pos: \"b\", h: 48 }\n CONFIG --> K11[\"Web Push (VAPID) keys\"]\n```\n\nThe Web Push (VAPID) keys are explained in [Web Push notifications and VAPID keys](https://ngx-ramblers.org.uk/how-to/technical-articles/2026-02-11-ngx-ramblers-architecture/web-push-vapid).\n\n\n\n## Technology Summary\n\n| Layer | Technology | Purpose |\n|-------|-----------|---------|\n| **Frontend** | Angular 21, Bootstrap 5, PrimeNG | SPA framework, UI components |\n| **Backend** | Node.js 24, Express, TypeScript | API server |\n| **Database** | MongoDB Atlas, Mongoose | Data persistence |\n| **Hosting** | Fly.io, Docker | Container hosting |\n| **CDN/DNS** | Cloudflare | DNS, SSL, email routing, CDN |\n| **Storage** | AWS S3, Sharp | File storage, image processing |\n| **Email (outbound)** | Brevo, Cloudflare | Transactional + bulk send, domain routing, SPF/DKIM/DMARC |\n| **Email (inbound)** | Gmail API, Google Cloud Pub/Sub, Web Push (VAPID) | In-app committee inbox, push notifications, live unread badge |\n| **Maps** | Leaflet, Google Maps, OS Maps | Map rendering, geocoding |\n| **Walks** | Ramblers API, Meetup API | Walk data sync, event publishing |\n| **CI/CD** | GitHub Actions, Docker | Build, test, deploy |\n| **Analytics** | Google Analytics 4 | User tracking |\n| **Security** | JWT, Passport.js, bcrypt, reCAPTCHA | Authentication, bot protection |","contentHtml":"

11-Feb-2026 — NGX Ramblers Architecture Overview

\n
\n

This article provides a visual tour of the NGX Ramblers platform architecture — every system, service, and integration that makes the application work. Use this as a reference when onboarding, debugging, or planning new features.

\n

High-Level Architecture

\n

NGX Ramblers is an Angular 21 single-page application backed by a Node.js/Express API, hosted on Fly.io, with MongoDB Atlas as the primary data store. Cloudflare handles DNS, SSL, and CDN — all user traffic passes through it before reaching Fly.io.

\n
flowchart LR\n    USER@{ icon: "ngx:user", label: "Users", pos: "b", h: 48 }\n    CF@{ icon: "ngx:cloudflare", label: "Cloudflare DNS/CDN", pos: "b", h: 48 }\n\n    USER --> CF\n\n    subgraph fly["Fly.io"]\n        FLY@{ icon: "logos:fly-icon", label: "Docker Container", pos: "b", h: 48 }\n        ANGULAR@{ icon: "logos:angular-icon", label: "Angular 21 SPA", pos: "b", h: 48 }\n        EXPRESS@{ icon: "ngx:express", label: "Express API", pos: "b", h: 48 }\n        FLY --> ANGULAR\n        ANGULAR --> EXPRESS\n        FLY --> EXPRESS\n    end\n\n    CF --> FLY\n    EXPRESS --> MONGO@{ icon: "ngx:mongodb", label: "MongoDB Atlas", pos: "b", h: 48 }\n    EXPRESS --> S3@{ icon: "ngx:aws", label: "AWS S3", pos: "b", h: 48 }\n    EXPRESS --> BREVO@{ icon: "ngx:brevo", label: "Brevo", pos: "b", h: 48 }\n    EXPRESS --> RAMBLERS@{ icon: "ngx:ramblers-hq", label: "Ramblers API", pos: "b", h: 48 }\n\n    style fly fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n
\n

Frontend Stack

\n

The Angular frontend uses a rich set of libraries for maps, charts, galleries, and UI components.

\n
flowchart LR\n    SPA@{ icon: "logos:angular-icon", label: "Angular 21", pos: "b", h: 48 }\n\n    subgraph ui["UI & Components"]\n        BS@{ icon: "logos:bootstrap", label: "Bootstrap 5", pos: "b", h: 48 }\n        FA["FontAwesome"]\n        PRIME["PrimeNG"]\n    end\n\n    subgraph maps["Maps"]\n        LEAF@{ icon: "logos:leaflet", label: "Leaflet", pos: "b", h: 48 }\n        GMAP@{ icon: "logos:google-maps", label: "Google Maps", pos: "b", h: 48 }\n        OS@{ icon: "ngx:os-maps", label: "OS Maps", pos: "b", h: 48 }\n    end\n\n    subgraph media["Media & Content"]\n        GALLERY["ng-gallery"]\n        CHARTS["Chart.js"]\n        MD["ngx-markdown"]\n        MERMAID["Mermaid"]\n    end\n\n    subgraph analytics["Analytics & Security"]\n        GA@{ icon: "logos:google-analytics", label: "Google Analytics", pos: "b", h: 48 }\n        RECAP@{ icon: "logos:recaptcha", label: "reCAPTCHA", pos: "b", h: 48 }\n    end\n\n    SPA --> ui\n    SPA --> maps\n    SPA --> media\n    SPA --> analytics\n\n    style ui fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n    style maps fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n    style media fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n    style analytics fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n
\n

Backend Integrations

\n

The Express API server connects to external services for data storage, email, DNS, event management, and walk data.

\n
flowchart LR\n    API@{ icon: "ngx:express", label: "Express API", pos: "b", h: 48 }\n\n    subgraph storage["Storage"]\n        MONGO@{ icon: "ngx:mongodb", label: "MongoDB Atlas", pos: "b", h: 48 }\n        S3@{ icon: "ngx:aws", label: "AWS S3", pos: "b", h: 48 }\n    end\n\n    subgraph email["Email"]\n        BREVO@{ icon: "ngx:brevo", label: "Brevo (send)", pos: "b", h: 48 }\n        GMAIL@{ icon: "logos:google-gmail", label: "Gmail API (inbox)", pos: "b", h: 48 }\n        PUBSUB@{ icon: "logos:google-cloud", label: "Google Cloud Pub/Sub", pos: "b", h: 48 }\n        MAILCHIMP@{ icon: "ngx:mailchimp", label: "Mailchimp (legacy)", pos: "b", h: 48 }\n    end\n\n    subgraph dns["DNS & Hosting"]\n        CF@{ icon: "ngx:cloudflare", label: "Cloudflare", pos: "b", h: 48 }\n        FLY@{ icon: "logos:fly-icon", label: "Fly.io", pos: "b", h: 48 }\n    end\n\n    subgraph walks["Walks & Events"]\n        RAMBLERS@{ icon: "ngx:ramblers-hq", label: "Ramblers API", pos: "b", h: 48 }\n        MEETUP@{ icon: "ngx:meetup", label: "Meetup API", pos: "b", h: 48 }\n    end\n\n    subgraph geo["Geolocation"]\n        GMAP@{ icon: "logos:google-maps", label: "Google Places", pos: "b", h: 48 }\n        POSTCODE["Postcode Lookup"]\n        OSMAP@{ icon: "ngx:os-maps", label: "OS Maps Proxy", pos: "b", h: 48 }\n    end\n\n    API --> storage\n    API --> email\n    API --> dns\n    API --> walks\n    API --> geo\n\n    style storage fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n    style email fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n    style dns fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n    style walks fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n    style geo fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n
\n

CI/CD Pipeline

\n

Code flows from GitHub through automated builds and tests, then deploys to Fly.io with secrets imported from a secure store.

\n
flowchart LR\n    DEV@{ icon: "logos:github-icon", label: "Push to main", pos: "b", h: 48 }\n    GHA@{ icon: "logos:github-actions", label: "GitHub Actions", pos: "b", h: 48 }\n    BUILD@{ icon: "logos:docker-icon", label: "Docker Build", pos: "b", h: 48 }\n    TEST@{ icon: "logos:typescript-icon", label: "Lint & Test", pos: "b", h: 48 }\n    SECRETS@{ icon: "ngx:mongodb", label: "Import Secrets", pos: "b", h: 48 }\n    DEPLOY@{ icon: "logos:fly-icon", label: "Deploy to Fly.io", pos: "b", h: 48 }\n\n    DEV --> GHA\n    GHA --> TEST\n    TEST --> BUILD\n    BUILD --> SECRETS\n    SECRETS --> DEPLOY\n
\n

Data Flow: Walk Publishing

\n

When a walk leader creates a walk, data flows through multiple systems to reach all audiences.

\n
flowchart LR\n    LEADER@{ icon: "ngx:user", label: "Walk Leader", pos: "b", h: 48 }\n    APP@{ icon: "ngx:ramblers", label: "NGX Ramblers", pos: "b", h: 48 }\n    DB@{ icon: "ngx:mongodb", label: "MongoDB", pos: "b", h: 48 }\n    RAPI@{ icon: "ngx:ramblers-hq", label: "Ramblers API", pos: "b", h: 48 }\n    MEETUP@{ icon: "ngx:meetup", label: "Meetup", pos: "b", h: 48 }\n    NOTIFY@{ icon: "ngx:brevo", label: "Email Notification", pos: "b", h: 48 }\n\n    LEADER -->|"Create walk"| APP\n    APP -->|"Save"| DB\n    APP -->|"Upload"| RAPI\n    APP -->|"Publish"| MEETUP\n    DB -->|"Trigger"| NOTIFY\n
\n

Email Architecture

\n

NGX Ramblers now handles email in both directions. Brevo and Cloudflare cover outbound sending and domain routing, and a built-in Gmail inbox brings inbound committee mail into the application itself — with browser push notifications the moment something arrives.

\n

Outbound: sending

\n

Outbound mail goes through Brevo. The unified email composer builds a message — WYSIWYG body, merge fields, recipient selection — and sends it either as a Brevo campaign (bulk) or, increasingly, as a server-side transactional batch job. Cloudflare email-routing rules and DNS records (SPF / DKIM / DMARC) keep delivery trustworthy.

\n
flowchart LR\n    COMPOSER@{ icon: "ngx:ramblers", label: "Email Composer", pos: "b", h: 48 }\n    BREVO@{ icon: "ngx:brevo", label: "Brevo API", pos: "b", h: 48 }\n    DELIVER@{ icon: "ngx:user", label: "Recipient Inbox", pos: "b", h: 48 }\n\n    COMPOSER -->|"campaign or transactional batch"| BREVO\n    BREVO --> DELIVER\n\n    CF@{ icon: "ngx:cloudflare", label: "Cloudflare", pos: "b", h: 48 }\n    CF -->|"DNS: SPF / DKIM / DMARC"| DELIVER\n
\n

Inbound: the Gmail inbox

\n

Committee role addresses (secretary@, membership@, and so on) are routed by Cloudflare into a dedicated Gmail mailbox, which NGX reads through the Gmail API over OAuth — so committee mail is handled inside the app rather than forwarded to someone's personal mail client. Messages reach the app two ways:

\n\n

Either way, each message is fetched, grouped into a thread, matched to the committee role it was addressed to, and stored in MongoDB (inboxMailboxConnections, inboxThreads, inboxMessages). The member assigned to that role reads and replies inside the app; replies go back out through the Brevo transactional path and are written back into the Gmail thread, so the mailbox stays consistent whether it is read in NGX or in Gmail.

\n
flowchart TB\n    SENDER@{ icon: "ngx:user", label: "External sender", pos: "b", h: 48 }\n    CF@{ icon: "ngx:cloudflare", label: "Cloudflare routing", pos: "b", h: 48 }\n    GMAIL@{ icon: "logos:google-gmail", label: "Dedicated Gmail mailbox", pos: "b", h: 48 }\n    PUBSUB@{ icon: "logos:google-cloud", label: "Google Cloud Pub/Sub", pos: "b", h: 48 }\n    APP@{ icon: "ngx:ramblers", label: "NGX Ramblers", pos: "b", h: 48 }\n    DB@{ icon: "ngx:mongodb", label: "threads + messages", pos: "b", h: 48 }\n    ROLE@{ icon: "ngx:user", label: "Committee role", pos: "b", h: 48 }\n\n    SENDER -->|"role address"| CF\n    CF -->|"forward"| GMAIL\n    GMAIL -->|"watch"| PUBSUB\n    PUBSUB -->|"push"| APP\n    GMAIL -->|"poll: history delta"| APP\n    APP -->|"fetch · thread · route"| DB\n    DB --> ROLE\n    ROLE -->|"reply via Brevo + writeback"| GMAIL\n
\n

Live notifications

\n

When an inbound message is stored, every member assigned to that role gets a browser push notification through a service worker and the Web Push (VAPID) protocol — no mail client open, no polling. The same signal drives the live unread badge in the admin UI.

\n
flowchart LR\n    NEW["New inbound message"]\n    APP@{ icon: "ngx:ramblers", label: "NGX Ramblers", pos: "b", h: 48 }\n    SW["Service Worker<br/>Web Push · VAPID"]\n    MEMBER@{ icon: "ngx:user", label: "Assigned member", pos: "b", h: 48 }\n\n    NEW --> APP\n    APP -->|"push to subscribers"| SW\n    SW -->|"notification + unread badge"| MEMBER\n
\n

One inbox, many providers

\n

The reader sits behind a provider interface (InboxReaderProvider). Gmail (gmail-api) is the implementation running in production today; the same interface leaves room for IMAP and other inbound sources (brevo-inbound-parse, cloudflare-ingress) without changing how threads, routing or notifications work.

\n

File & Image Storage

\n

User-uploaded images pass through server-side processing before reaching S3.

\n
flowchart LR\n    UPLOAD@{ icon: "logos:angular-icon", label: "Upload from UI", pos: "b", h: 48 }\n    PROCESS@{ icon: "logos:nodejs-icon", label: "Resize (Sharp)", pos: "b", h: 48 }\n    STORE@{ icon: "ngx:aws", label: "AWS S3", pos: "b", h: 48 }\n    SERVE@{ icon: "ngx:user", label: "Serve to browser", pos: "b", h: 48 }\n\n    UPLOAD --> PROCESS --> STORE --> SERVE\n
\n

Maps & Geolocation

\n

Multiple mapping services work together to provide rich location features.

\n
flowchart TD\n    LEAF@{ icon: "logos:leaflet", label: "Leaflet", pos: "b", h: 48 }\n\n    subgraph tiles["Tile Layers"]\n        OSM@{ icon: "logos:openstreetmap", label: "OpenStreetMap", pos: "b", h: 48 }\n        OSMAP@{ icon: "ngx:os-maps", label: "OS Maps (UK)", pos: "b", h: 48 }\n    end\n\n    subgraph search["Location Search"]\n        GMAP@{ icon: "logos:google-maps", label: "Google Places", pos: "b", h: 48 }\n        POST["Postcode Lookup"]\n        ORS["OpenRouteService"]\n    end\n\n    LEAF --> tiles\n    LEAF --> search\n\n    style tiles fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n    style search fill:#E8F5EE,stroke:#9BC8AB,stroke-width:2px,rx:12,ry:12,color:#404143\n
\n

Authentication & Security

\n

The application uses JWT for API authentication, with bcrypt for password storage and reCAPTCHA for public forms.

\n
flowchart LR\n    LOGIN@{ icon: "ngx:user", label: "Login", pos: "b", h: 48 }\n    AUTH["Passport.js + JWT"]\n    HASH["bcrypt"]\n    DB@{ icon: "ngx:mongodb", label: "Member Record", pos: "b", h: 48 }\n    RECAP@{ icon: "logos:recaptcha", label: "reCAPTCHA v3", pos: "b", h: 48 }\n    CONTACT@{ icon: "ngx:user", label: "Contact Form", pos: "b", h: 48 }\n\n    LOGIN --> AUTH --> DB\n    AUTH --> HASH\n    CONTACT --> RECAP\n
\n

System Configuration

\n

All external service credentials and feature flags are stored centrally in MongoDB under the config collection.

\n
flowchart TD\n    CONFIG@{ icon: "ngx:mongodb", label: "Config Collection", pos: "b", h: 48 }\n\n    CONFIG --> K1@{ icon: "ngx:aws", label: "AWS", pos: "b", h: 48 }\n    CONFIG --> K2@{ icon: "ngx:cloudflare", label: "Cloudflare", pos: "b", h: 48 }\n    CONFIG --> K3@{ icon: "ngx:brevo", label: "Brevo", pos: "b", h: 48 }\n    CONFIG --> K4@{ icon: "logos:google-maps", label: "Google Maps", pos: "b", h: 48 }\n    CONFIG --> K5@{ icon: "logos:recaptcha", label: "reCAPTCHA", pos: "b", h: 48 }\n    CONFIG --> K6@{ icon: "ngx:meetup", label: "Meetup", pos: "b", h: 48 }\n    CONFIG --> K7@{ icon: "ngx:ramblers-hq", label: "Ramblers API", pos: "b", h: 48 }\n    CONFIG --> K8@{ icon: "logos:google-analytics", label: "Google Analytics", pos: "b", h: 48 }\n    CONFIG --> K9@{ icon: "logos:google-gmail", label: "Gmail OAuth (inbox)", pos: "b", h: 48 }\n    CONFIG --> K10@{ icon: "logos:google-cloud", label: "Google Cloud Pub/Sub", pos: "b", h: 48 }\n    CONFIG --> K11["Web Push (VAPID) keys"]\n
\n

The Web Push (VAPID) keys are explained in Web Push notifications and VAPID keys.

\n

Technology Summary

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
LayerTechnologyPurpose
FrontendAngular 21, Bootstrap 5, PrimeNGSPA framework, UI components
BackendNode.js 24, Express, TypeScriptAPI server
DatabaseMongoDB Atlas, MongooseData persistence
HostingFly.io, DockerContainer hosting
CDN/DNSCloudflareDNS, SSL, email routing, CDN
StorageAWS S3, SharpFile storage, image processing
Email (outbound)Brevo, CloudflareTransactional + bulk send, domain routing, SPF/DKIM/DMARC
Email (inbound)Gmail API, Google Cloud Pub/Sub, Web Push (VAPID)In-app committee inbox, push notifications, live unread badge
MapsLeaflet, Google Maps, OS MapsMap rendering, geocoding
WalksRamblers API, Meetup APIWalk data sync, event publishing
CI/CDGitHub Actions, DockerBuild, test, deploy
AnalyticsGoogle Analytics 4User tracking
SecurityJWT, Passport.js, bcrypt, reCAPTCHAAuthentication, bot protection
\n"}