# charizard00001/r-land-hunt architecture

> Architecture diagram of the GitHub repository charizard00001/r-land-hunt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/charizard00001/r-land-hunt
- Repository: https://github.com/charizard00001/r-land-hunt

## Overview

##### Project type and purpose
- This is a full-stack web application (“R-Land Hunt”) for managing and playing location-based scavenger hunts.
- The **README** confirms two roles: an **admin** section for creating/managing hunts, and a **participant** section for viewing clues, leaderboards, and taking the hunt.
- Tech stack: **Node.js + Express** on the server, **EJS** templates + CSS/JS on the client, and a JavaScript-based database connector in `data/database.js`.

##### File structure
- **Entry point**: `index.js`
- **Configuration**: `config/session.js` (session setup)
- **Middleware**: `middlewares/` (authentication, CSRF token, error handling)
- **Routing**: `routes/` (separate route files for Oauth, auth, etc.)
- **Controllers**: `controllers/` (one controller per feature: auth, startHunt, huntInfo, etc.)
- **Models**: `models/` (User, Team, Hunt)
- **Data access**: `data/database.js` (DB connection and queries)
- **Utilities**: `util/` (authentication helpers, flash messages)
- **Presentation**:
- `views/` (EJS templates, includes)
- `public/` (static assets: CSS under `/CSS`, client-side JS under `/scripts`)

##### Key architectural observations
- MVC-inspired pattern:
- **Models** encapsulate data schemas and DB operations.
- **Views** (EJS) render server-side HTML, injecting dynamic data.
- **Controllers** handle HTTP requests, call models, choose views or JSON responses.
- **Middleware pipeline** implements cross-cutting concerns (auth checks, CSRF protection, error handling).
- **Session management** for login state.
- Likely uses a single Node/Express process behind a hosting platform (Render).

##### Components
a. Presentation layer (Clients)
- Web browser, mobile browser
- Static assets: CSS files, client-side JS (geolocation, clue submission, leaderboard UI)
- EJS-rendered pages (login, register, hunt pages)
b. Application layer (Express server)
- `index.js` – Express app initialization
- Middleware chain (CSRF, check-auth, error handler)
- Router modules (`routes/*.js`)
- Controller modules handling business logic
- Utility modules (authentication helpers, flash messaging)
c. Data layer
- Database service (e.g., MongoDB or SQL engine)
- `data/database.js` – DB connector
- Model modules (`models/*.model.js`)
d. External services (optional)
- Geolocation API (client browser geolocation)
- Hosting platform (Render.com)
- OAuth providers if used (see `routes/Oauth.routes.js`)

##### Relationships and interactions
- Browser → HTTP(S) request → Express server
- Express → middleware → route matching → controller invocation
- Controller → model calls → database queries → data returned
- Controller → choose view template + data → EJS renders HTML → HTTP response → browser
- Client-side JS may make AJAX calls back to server controllers (e.g., fetching next clue, submitting hints)
- Session store interaction for maintaining user state between requests

##### Architectural patterns & principles
- Separation of concerns (presentation vs. business logic vs. data access)
- Layered architecture
- RESTful routing for resources (auth, hunts, teams)
- Modularization by feature (controllers + models per domain concept)
- Use of middleware for cross-cutting concerns

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Browser["Web / Mobile Browser"]:::client
        StaticAssetsCSS["CSS Files"]:::client
        ClientScripts["Client-side JS"]:::client
        EJSViews["EJS Templates"]:::client
    end

    %% Server Layer
    subgraph "Server Layer"
        direction TB
        Entry["index.js"]:::server
        SessionConfig["Session Config"]:::server
        subgraph "Middleware Pipeline"
            direction TB
            CSRF["CSRF Protection"]:::server
            AuthGuard["Authentication Guard"]:::server
            ErrorHandler["Error Handler"]:::server
        end
        subgraph "Routes"
            direction TB
            OAuthRoutes["OAuth Routes"]:::server
            AuthRoutes["Auth Routes"]:::server
        end
        subgraph "Controllers"
            direction TB
            AuthController["Authentication Controller"]:::server
            EditHuntController["Hunt Creation/Editing Controller"]:::server
            EnterHuntController["Hunt Entry Controller"]:::server
            HuntInfoController["Hunt Info Controller"]:::server
            StartHuntController["Hunt Start Controller"]:::server
            TeamController["Team Management Controller"]:::server
            UpcomingController["Upcoming Hunts Controller"]:::server
        end
        subgraph "Utilities"
            direction TB
            AuthHelpers["Authentication Helpers"]:::util
            FlashHelpers["Flash Session Helpers"]:::util
        end
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DBConnector["Database Connector"]:::data
        subgraph "Models"
            direction TB
            HuntModel["Hunt Model"]:::data
            TeamModel["Team Model"]:::data
            UserModel["User Model"]:::data
        end
        Database[(Database Engine)]:::data
    end

    %% Relationships
    Browser -->|"HTTP Requests"| Entry
    Browser -->|loads| StaticAssetsCSS
    Browser -->|loads| ClientScripts
    Browser -->|renders| EJSViews

    Entry --> SessionConfig
    SessionConfig --> CSRF
    CSRF --> AuthGuard
    AuthGuard --> ErrorHandler
    ErrorHandler --> OAuthRoutes
    ErrorHandler --> AuthRoutes

    OAuthRoutes --> AuthController
    AuthRoutes --> AuthController

    AuthController --> AuthHelpers
    AuthController --> DBConnector

    OAuthRoutes --> EditHuntController
    EditHuntController --> DBConnector
    EnterHuntController --> DBConnector
    HuntInfoController --> DBConnector
    StartHuntController --> DBConnector
    TeamController --> DBConnector
    UpcomingController --> DBConnector

    DBConnector --> HuntModel
    DBConnector --> TeamModel
    DBConnector --> UserModel

    HuntModel --> Database
    TeamModel --> Database
    UserModel --> Database

    %% Click events
    click StaticAssetsCSS "https://github.com/charizard00001/r-land-hunt/tree/main/public/CSS/"
    click ClientScripts "https://github.com/charizard00001/r-land-hunt/tree/main/public/scripts/"
    click EJSViews "https://github.com/charizard00001/r-land-hunt/tree/main/views/"
    click Entry "https://github.com/charizard00001/r-land-hunt/blob/main/index.js"
    click SessionConfig "https://github.com/charizard00001/r-land-hunt/blob/main/config/session.js"
    click AuthGuard "https://github.com/charizard00001/r-land-hunt/blob/main/middlewares/check-auth.js"
    click CSRF "https://github.com/charizard00001/r-land-hunt/blob/main/middlewares/csrf-token.js"
    click ErrorHandler "https://github.com/charizard00001/r-land-hunt/blob/main/middlewares/error-handler.js"
    click OAuthRoutes "https://github.com/charizard00001/r-land-hunt/blob/main/routes/Oauth.routes.js"
    click AuthRoutes "https://github.com/charizard00001/r-land-hunt/blob/main/routes/auth.routes.js"
    click AuthController "https://github.com/charizard00001/r-land-hunt/blob/main/controllers/auth.controller.js"
    click EditHuntController "https://github.com/charizard00001/r-land-hunt/blob/main/controllers/edithunt.controller.js"
    click EnterHuntController "https://github.com/charizard00001/r-land-hunt/blob/main/controllers/enterhunt.controller.js"
    click HuntInfoController "https://github.com/charizard00001/r-land-hunt/blob/main/controllers/huntinfo.controller.js"
    click StartHuntController "https://github.com/charizard00001/r-land-hunt/blob/main/controllers/starthunt.controller.js"
    click TeamController "https://github.com/charizard00001/r-land-hunt/blob/main/controllers/team.controller.js"
    click UpcomingController "https://github.com/charizard00001/r-land-hunt/blob/main/controllers/upcomings.controller.js"
    click AuthHelpers "https://github.com/charizard00001/r-land-hunt/blob/main/util/authentication.js"
    click FlashHelpers "https://github.com/charizard00001/r-land-hunt/blob/main/util/session-flash.js"
    click DBConnector "https://github.com/charizard00001/r-land-hunt/blob/main/data/database.js"
    click HuntModel "https://github.com/charizard00001/r-land-hunt/blob/main/models/hunt.model.js"
    click TeamModel "https://github.com/charizard00001/r-land-hunt/blob/main/models/team.model.js"
    click UserModel "https://github.com/charizard00001/r-land-hunt/blob/main/models/user.model.js"

    %% Styles
    classDef client fill:#FFA500,stroke:#333,stroke-width:1px
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef data fill:#90EE90,stroke:#333,stroke-width:1px
    classDef util fill:#FFFF66,stroke:#333,stroke-width:1px
```
