4hprojects/hellorun

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.