# 4hprojects/hellorun architecture

> Architecture diagram of the GitHub repository 4hprojects/hellorun, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/4hprojects/hellorun
- Repository: https://github.com/4hprojects/hellorun

## Overview

1. **What this repository is**
   - HelloRun is a server-rendered Node.js web platform built around a single Express application.
   - It combines public marketing pages, authenticated runner/organizer/admin portals, event operations, submissions, certificates, blog content, and a shop/commerce module.

2. **Primary runtime and delivery model**
   - The app is rendered mostly with EJS templates under `src/views`, with shared layouts and partials.
   - Static assets live in `src/public` and are complemented by some root-level `css/` and `js/` files.
   - The main entrypoint is `src/server.js`, with routing and middleware layered around it.

3. **Request handling architecture**
   - Requests flow through route modules in `src/routes`, then through middleware, then into controllers.
   - Controllers are thin HTTP adapters; business logic is pushed into `src/services`, and persistence is handled through models and database helpers.
   - This separation is important for drawing the system boundary: routes/middleware at the edge, services in the center, database/models at the core.

4. **Identity, roles, and access control**
   - The app has a role-aware authorization model with at least three major personas: runner, organizer, and admin.
   - Cross-cutting middleware enforces auth, CSRF, rate limits, role checks, organizer-event access, and shop access.
   - The README confirms dual-role support: an organizer can also be a runner, so role logic is not mutually exclusive.

5. **Core product domain: events and participation**
   - The main domain is running events: event creation, registration, public event pages, leaderboards, rankings, and results/submission review.
   - Key services such as `event-shadow`, `event-approval`, `registration-price`, `ranking`, `leaderboard`, and `public-event-list` indicate a workflow where public discovery, registration, and result tracking are separate concerns.
   - The event subsystem has both public-facing pages and organizer-managed operational views.

6. **Runner workflow**
   - Runner-facing screens center on profile, dashboard, notifications, submissions, groups, badges, certificates, and event progress.
   - Data flows for runners include registration history, accumulated activity, submission review state, leaderboard placement, and achievement progress.
   - This area is represented by dedicated runner routes, runner controller logic, and dashboard partials that assemble many independent data widgets.

7. **Organizer workflow**
   - Organizer functionality includes application onboarding, profile completion, event creation/editing, registrant management, submission review, onsite operations, QR/dashboard tools, payment proof review, and event-level shop management.
   - There is a clear boundary between organizer self-service and admin oversight: organizers manage their own events, while admins review applications, govern policies, and handle platform-wide controls.
   - Docs and routes show a mature workflow around event creation and organizer verification documents.

8. **Admin and moderation layer**
   - The admin area includes user management, event oversight, blog moderation, communications, ads, badges, shop administration, submissions review, and policy content editing.
   - Admin-specific pages and controllers suggest a central operations console rather than a separate application.
   - Moderation flows appear in blog reports, review queues, payment reviews, and critical audit services.

9. **Content, blog, and policy management**
   - The platform includes a blog subsystem with authorship, revisions, comments, likes, views, trending, and scheduled publishing.
   - Static and governed content includes policy pages, cookie/privacy/terms packs, FAQ/about/contact pages, and SEO-oriented public pages.
   - This content layer is not just informational; it supports trust, compliance, and discovery for the platform.

10. **Commerce and monetization**
   - There is a separate shop subsystem for products, variants, inventory, cart/checkout, order management, payment review, and organizer vs platform product boundaries.
   - Shop access is mediated by dedicated middleware and mirrored in both organizer and admin consoles.
   - The architecture implies commerce is embedded into the same app, but kept logically isolated from event registration and submissions.

11. **Certificates, badges, and proof verification**
   - Certificate generation and verification are first-class workflows, with a template system and dedicated verification pages.
   - Achievement badges are also a separate subsystem, with templates, content, progress, notifications, and audits.
   - Run proof handling is supported by OCR-focused client scripts and server-side integrity/review services, indicating automated plus manual validation.

12. **Data storage and migration strategy**
   - The persistence layer is PostgreSQL-based, with explicit migration history under `src/db/migrations`.
   - The schema shows phased expansion, including shadow tables and backfill/verification scripts for app users, event core, registration payment, submissions/certificates, rankings, and onsite operations.
   - This suggests a hybrid architecture where legacy data is gradually bridged into the current schema rather than migrated in one step.

13. **Supporting infrastructure and integrations**
   - Redis is present in `src/config/redis.js`, likely for sessions, rate limiting, caching, or transient workflow state.
   - Upload handling is built in, with services, setup scripts, and upload directories for event images, organizer docs, and profile photos.
   - External integrations include Google OAuth, Strava, OCR tooling, and a webhook route for timing-system data.

14. **Operational scripts and test coverage**
   - The repo includes many maintenance scripts: backfills, cleanup, seeding, smoke tests, verification jobs, and live-sync checks.
   - The test suite is broad and integration-heavy, covering auth, event flows, organizers, runners, shop, certificates, OCR, policies, security, and rate limiting.
   - For architecture diagrams, this indicates a production monolith with significant operational tooling around database consistency and phased feature rollout.

Main entry points: [`src/services`](https://github.com/4hprojects/hellorun/tree/main/src/services) (Services), [`src/routes`](https://github.com/4hprojects/hellorun/tree/main/src/routes) (Routes), [`src/controllers`](https://github.com/4hprojects/hellorun/tree/main/src/controllers) (Controllers), [`src/views`](https://github.com/4hprojects/hellorun/tree/main/src/views) (Views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_src_server["Server<br/>express entrypoint<br/>[server.js]"]
  node_src_routes["Routes<br/>http routing"]
  node_src_middleware["Middleware<br/>edge guards"]
  node_src_controllers["Controllers<br/>http adapters"]
  node_src_views["Views<br/>ejs templates"]
end

subgraph group_domains["Product domains"]
  node_src_services["Services<br/>business logic"]
  node_runner_portal["Runner portal<br/>runner workflow"]
  node_organizer_portal["Organizer portal<br/>organizer workflow"]
  node_admin_console["Admin console<br/>admin operations"]
  node_event_system(("Events<br/>event domain"))
  node_submission_system(("Submissions<br/>proof workflow"))
  node_certificates_badges(("Certificates<br/>achievement system"))
  node_shop_system(("Shop<br/>commerce module<br/>[order.service.js]"))
end

subgraph group_content["Content"]
  node_blog_content(("Blog<br/>content platform"))
  node_policy_pages["Policies<br/>governed content<br/>[policy.ejs]"]
end

subgraph group_infra["Infrastructure"]
  node_db_layer[("Postgres<br/>persistence core<br/>[db.js]")]
  node_migrations["Migrations<br/>schema history"]
  node_models["Models"]
  node_uploads["Uploads<br/>file storage"]
  node_integrations{{"Integrations<br/>external systems<br/>[strava.service.js]"}}
  node_ops_scripts["Ops scripts<br/>maintenance jobs"]
end

node_src_server -->|"mounts"| node_src_routes
node_src_server -->|"applies"| node_src_middleware
node_src_routes -->|"dispatches to"| node_src_controllers
node_src_controllers -->|"calls"| node_src_services
node_src_services -->|"reads/writes"| node_models
node_models -->|"uses"| node_db_layer
node_db_layer -->|"evolves via"| node_migrations
node_src_controllers -->|"renders"| node_src_views
node_src_views -->|"includes"| node_runner_portal
node_src_views -->|"includes"| node_organizer_portal
node_src_views -->|"includes"| node_admin_console
node_src_services -->|"covers"| node_event_system
node_src_services -->|"covers"| node_submission_system
node_src_services -->|"covers"| node_certificates_badges
node_src_services -->|"covers"| node_shop_system
node_src_services -->|"covers"| node_blog_content
node_src_routes -->|"serves"| node_policy_pages
node_src_services -->|"stores files"| node_uploads
node_src_services -->|"integrates"| node_integrations
node_ops_scripts -.->|"runs"| node_migrations
node_ops_scripts -.->|"repairs"| node_db_layer
node_src_middleware -->|"guards"| node_src_routes
node_src_controllers -->|"served by"| node_src_routes

click node_src_server "https://github.com/4hprojects/hellorun/blob/main/src/server.js"
click node_src_routes "https://github.com/4hprojects/hellorun/tree/main/src/routes"
click node_src_middleware "https://github.com/4hprojects/hellorun/tree/main/src/middleware"
click node_src_controllers "https://github.com/4hprojects/hellorun/tree/main/src/controllers"
click node_src_views "https://github.com/4hprojects/hellorun/tree/main/src/views"
click node_src_services "https://github.com/4hprojects/hellorun/tree/main/src/services"
click node_runner_portal "https://github.com/4hprojects/hellorun/tree/main/src/views/runner"
click node_organizer_portal "https://github.com/4hprojects/hellorun/tree/main/src/views/organizer"
click node_admin_console "https://github.com/4hprojects/hellorun/tree/main/src/views/admin"
click node_event_system "https://github.com/4hprojects/hellorun/blob/main/src/services/event-approval.service.js"
click node_submission_system "https://github.com/4hprojects/hellorun/blob/main/src/services/submission.service.js"
click node_certificates_badges "https://github.com/4hprojects/hellorun/blob/main/src/services/certificate.service.js"
click node_shop_system "https://github.com/4hprojects/hellorun/blob/main/src/services/shop/order.service.js"
click node_blog_content "https://github.com/4hprojects/hellorun/blob/main/src/services/blog-trending.service.js"
click node_policy_pages "https://github.com/4hprojects/hellorun/blob/main/src/views/pages/policy.ejs"
click node_db_layer "https://github.com/4hprojects/hellorun/blob/main/src/config/db.js"
click node_migrations "https://github.com/4hprojects/hellorun/tree/main/src/db/migrations"
click node_models "https://github.com/4hprojects/hellorun/tree/main/src/models"
click node_uploads "https://github.com/4hprojects/hellorun/tree/main/src/public/uploads"
click node_integrations "https://github.com/4hprojects/hellorun/blob/main/src/services/strava.service.js"
click node_ops_scripts "https://github.com/4hprojects/hellorun/tree/main/src/scripts"

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_src_server,node_src_routes,node_src_middleware,node_src_controllers,node_src_views toneBlue
class node_src_services,node_runner_portal,node_organizer_portal,node_admin_console,node_event_system,node_submission_system,node_certificates_badges,node_shop_system toneAmber
class node_blog_content,node_policy_pages toneMint
class node_db_layer,node_migrations,node_models,node_uploads,node_integrations,node_ops_scripts toneRose
```

## Components

### Runtime

Express app, middleware, and server-rendered delivery

- [Server](https://github.com/4hprojects/hellorun/blob/main/src/server.js): express entrypoint · Main Node.js entrypoint that boots the app and wires middleware/routes. · `src/server.js`
- [Routes](https://github.com/4hprojects/hellorun/tree/main/src/routes): http routing · Route layer that splits traffic across auth, pages, runner, organizer, admin, shop, and webhooks. · `src/routes`
- [Middleware](https://github.com/4hprojects/hellorun/tree/main/src/middleware): edge guards · Cross-cutting auth, CSRF, rate limit, role, shop, and organizer-event access controls. · `src/middleware`
- [Controllers](https://github.com/4hprojects/hellorun/tree/main/src/controllers): http adapters · Thin request handlers that adapt route inputs to services and views. · `src/controllers`
- [Views](https://github.com/4hprojects/hellorun/tree/main/src/views): ejs templates · Server-rendered EJS pages, layouts, and partials for public and authenticated screens. · `src/views`

### Product domains

Core user-facing workflows and business capabilities

- [Services](https://github.com/4hprojects/hellorun/tree/main/src/services): business logic · Core application logic spanning events, runners, organizer operations, content, certificates, shop, and integrations. · `src/services`
- [Runner portal](https://github.com/4hprojects/hellorun/tree/main/src/views/runner): runner workflow · Runner dashboard, profile, notifications, groups, submissions, badges, and certificates. · `src/views/runner`
- [Organizer portal](https://github.com/4hprojects/hellorun/tree/main/src/views/organizer): organizer workflow · Organizer onboarding, profile completion, event creation, registrants, submissions, onsite ops, and event shop management. · `src/views/organizer`
- [Admin console](https://github.com/4hprojects/hellorun/tree/main/src/views/admin): admin operations · Platform oversight for users, events, moderation, communications, ads, badges, and shop administration. · `src/views/admin`
- [Events](https://github.com/4hprojects/hellorun/blob/main/src/services/event-approval.service.js): event domain · Public event discovery, registration, approvals, leaderboards, rankings, and event lifecycle management. · `src/services/event-approval.service.js`
- [Submissions](https://github.com/4hprojects/hellorun/blob/main/src/services/submission.service.js): proof workflow · Run proof intake, review, shadow validation, and submission integrity handling. · `src/services/submission.service.js`
- [Certificates](https://github.com/4hprojects/hellorun/blob/main/src/services/certificate.service.js): achievement system · Certificate templates, verification, badge content, progress, notification, and audit workflows. · `src/services/certificate.service.js`
- [Shop](https://github.com/4hprojects/hellorun/blob/main/src/services/shop/order.service.js): commerce module · Products, variants, inventory, carts, orders, and payment review for platform and organizer commerce. · `src/services/shop/order.service.js`

### Content

Blog, policies, and governed public pages

- [Blog](https://github.com/4hprojects/hellorun/blob/main/src/services/blog-trending.service.js): content platform · Blog publishing, revisions, comments, likes, views, trending, and author tooling. · `src/services/blog-trending.service.js`
- [Policies](https://github.com/4hprojects/hellorun/blob/main/src/views/pages/policy.ejs): governed content · Privacy, terms, cookie policy, FAQ/about/contact, and other trust-oriented public pages. · `src/views/pages/policy.ejs`

### Infrastructure

Storage, uploads, integrations, and operational tooling

- [Postgres](https://github.com/4hprojects/hellorun/blob/main/src/config/db.js): persistence core · Database connection and schema-backed persistence for users, events, registrations, submissions, shop, and content. · `src/config/db.js`
- [Migrations](https://github.com/4hprojects/hellorun/tree/main/src/db/migrations): schema history · Phased SQL migration set including shadow tables, backfills, and feature rollouts. · `src/db/migrations`
- [Models](https://github.com/4hprojects/hellorun/tree/main/src/models): data models · Database-facing model layer for users, events, blogs, submissions, certificates, shop, badges, and settings. · `src/models`
- [Uploads](https://github.com/4hprojects/hellorun/tree/main/src/public/uploads): file storage · Uploaded event images, organizer documents, and profile photos served from public storage. · `src/public/uploads`
- [Integrations](https://github.com/4hprojects/hellorun/blob/main/src/services/strava.service.js): external systems · Google OAuth, Strava, OCR tooling, timing-system webhooks, and Redis-backed runtime support. · `src/services/strava.service.js`
- [Ops scripts](https://github.com/4hprojects/hellorun/tree/main/src/scripts): maintenance jobs · Backfills, smoke tests, verification jobs, seeding, cleanup, sync, and publish automation. · `src/scripts`

## Connections

- Server → Routes: mounts · Server attaches the route modules.
- Server → Middleware: applies · Server wires shared request guards and processing.
- Routes → Controllers: dispatches to · Routes hand requests to controllers.
- Controllers → Services: calls · Controllers delegate business logic to services.
- Services → Models: reads/writes · Services use models for domain persistence.
- Models → Postgres: uses · Models persist through the Postgres layer.
- Postgres → Migrations: evolves via · Schema changes are managed by SQL migrations.
- Controllers → Views: renders · Controllers render server-side templates.
- Views → Runner portal: includes · Runner templates assemble dashboard and workflow pages.
- Views → Organizer portal: includes · Organizer templates assemble event operations pages.
- Views → Admin console: includes · Admin templates assemble moderation and platform ops pages.
- Services → Events: covers · Event, registration, ranking, leaderboard, and approval logic.
- Services → Submissions: covers · Submission intake, review, and integrity logic.
- Services → Certificates: covers · Certificate and badge workflows.
- Services → Shop: covers · Commerce, inventory, ordering, and payment review.
- Services → Blog: covers · Blog composition, publishing, interaction, and trending.
- Routes → Policies: serves · Public and policy routes expose governed pages.
- Services → Uploads: stores files · Upload service and related workflows write media and documents.
- Services → Integrations: integrates · Services coordinate OAuth, Strava, OCR, Redis, and webhooks.
- Ops scripts → Migrations: runs · Operational scripts apply or validate database changes.
- Ops scripts → Postgres: repairs · Backfills and verifications operate against live data.
- Middleware → Routes: guards · Access control and request validation protect routes.
- Controllers → Routes: served by · Controllers are exposed through route modules.