# decouverto/decouverto-website architecture

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

- Interactive diagram: https://gitdiagram.com/decouverto/decouverto-website
- Repository: https://github.com/decouverto/decouverto-website

## Overview

##### Project Type and Purpose
- This is a full-stack Node.js/Express web application that powers the Découverto website.
- It provides a public-facing site (walks, books, categories) rendered via EJS templates, plus an admin SPA (AngularJS/TinyMCE) under “public/javascripts/admin”.
- Data is stored in MongoDB, and backend tasks regularly email stats via Nodemailer.

##### File Structure Analysis
- Top-level:
- app.js: application entry point, sets up Express, middleware, routes.
- routes/: REST endpoints for “walks”, “shops”, “users”, “highlights”, plus admin UI route.
- models/: Mongoose schemas (users, etc.).
- policies/: authorization middleware.
- libs/: utility modules (elevation, GPX, template caching).
- public/: static assets (CSS/JS/fonts/images) for both public and admin clients.
- views/: server-rendered EJS templates for public pages.
- tasks/: scheduled Node scripts (send-stats, etc.).
- bin/: service and Docker helper scripts (startup, systemd unit).
- Configuration & deployment:
- Dockerfile, docker-compose.yml / docker-compose-dev.yml for containerization.
- Caddyfile for reverse proxy.
- .env-driven configuration (mail service, replica mode).

##### Key Components & Interactions
a. Client Layer
- Public Browser: requests HTML, JS, CSS via Caddy → Node.
- Admin Browser: AngularJS SPA under /admin served from public/javascripts.
b. Web Server / Reverse Proxy
- Caddy: SSL, virtual hosts, forwards HTTP(S) to Node.js on port 8080.
c. Application Layer
- Node.js/Express (app.js):
- Serves static assets from public/.
- Renders EJS views for public routes.
- Exposes JSON REST API endpoints for data.
- Applies auth policies for protected admin routes.
- Loads libs for geodata, caching, GPX export.
- Runs scheduled tasks (via cron in container or external scheduler) under tasks/.
d. Data Layer
- MongoDB: stores collections for users, walks, shops, highlights, metas, stats.
e. External Services
- SMTP (Nodemailer): sends weekly summary emails (configured via .env).
- Optional: Replica nodes if IS_REPLICA=true for read-scaling.

##### Architectural Patterns
- MVC / Layered:
- Models (Mongoose in models/)
- Controllers / Routers (routes/)
- Views (EJS in views/ and AngularJS for admin).
- RESTful API for client JavaScript modules (under public/javascripts/*).
- Task Scheduler: decoupled “tasks” folder, invoked on a cron schedule or via Docker Compose command.
- Containerized micro-service style: separate Caddy, Node app, MongoDB.

a. Components
- User’s Web Browser (public vs. admin)
- Caddy Reverse Proxy (TLS termination)
- Node.js App Server (Express)
- MongoDB Database
- SMTP Service (external)
- Scheduled Task Runner (within Node container or separate)
b. Relationships & Data Flows
c. Technologies & Libraries
- Node.js, Express, Mongoose, EJS, AngularJS/TinyMCE, Nodemailer, Docker, Caddy
d. Design Principles
- Separation of concerns (static assets vs. API vs. tasks)
- Clear layering (client, API, persistence)
- Containerized deployment (Docker Compose)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        PublicUI["Public Browser"]:::request
        AdminUI["Admin Browser"]:::request
    end

    %% Reverse Proxy Layer
    Caddy["Caddy Reverse Proxy"]:::request

    %% Application Layer
    subgraph "Express Server" 
        direction TB
        AppJS["app.js"]:::request
        Routes["routes/ (REST & pages)"]:::request
        Models["models/"]:::datastore
        Policies["policies/"]:::request
        Libs["libs/"]:::request
        PublicAssets["public/ (static assets)"]:::request
        Templates["views/ (EJS templates)"]:::request
    end

    %% Task Scheduler
    subgraph "Scheduled Tasks" 
        direction TB
        Cron["Cron Scheduler"]:::tasks
        TaskRunner["tasks/send-stats.js"]:::tasks
    end

    %% Data & External Services
    MongoDB["MongoDB Database"]:::datastore
    SMTP["SMTP Service"]:::external

    %% Connections
    PublicUI -->|"HTTPS"| Caddy
    AdminUI -->|"HTTPS"| Caddy
    Caddy -->|"HTTP"| AppJS
    AppJS --> Routes
    AppJS --> Models
    AppJS --> Policies
    AppJS --> Libs
    AppJS --> PublicAssets
    AppJS --> Templates
    AppJS -->|"MongoDB queries"| MongoDB
    AppJS -->|"send email via SMTP"| SMTP

    Cron -->|"invokes"| TaskRunner
    TaskRunner -->|"read/write"| MongoDB
    TaskRunner -->|"send stats via SMTP"| SMTP

    %% Click Events
    click PublicUI "https://github.com/decouverto/decouverto-website/blob/master/views/index.ejs"
    click Templates "https://github.com/decouverto/decouverto-website/blob/master/views/admin.ejs"
    click PublicAssets "https://github.com/decouverto/decouverto-website/tree/master/public/javascripts/admin/"
    click AppJS "https://github.com/decouverto/decouverto-website/blob/master/app.js"
    click Routes "https://github.com/decouverto/decouverto-website/blob/master/routes/index.js"
    click Models "https://github.com/decouverto/decouverto-website/blob/master/models/index.js"
    click Policies "https://github.com/decouverto/decouverto-website/blob/master/policies/auth.js"
    click Libs "https://github.com/decouverto/decouverto-website/blob/master/libs/get-elevation.js"
    click TaskRunner "https://github.com/decouverto/decouverto-website/blob/master/tasks/send-stats.js"

    %% Styles
    classDef request fill:#AED6F1,stroke:#1474A3,color:#000
    classDef datastore fill:#ABEBC6,stroke:#196F3D,color:#000
    classDef external fill:#F5CBA7,stroke:#B9770E,color:#000
    classDef tasks fill:#F9E79F,stroke:#B7950B,color:#000,stroke-dasharray: 5 5
```
