# kyrawest/runningthoughts architecture

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

- Interactive diagram: https://gitdiagram.com/kyrawest/runningthoughts
- Repository: https://github.com/kyrawest/runningthoughts

## Overview

##### Project type and purpose
- Full-stack server-rendered web application.
- Built on Node.js/Express with server-side EJS templates and Bootstrap.
- Organizes spoken or typed notes into “runs” per user, with authentication (Passport.js) and MongoDB persistence.

##### Main components
a. Frontend (Browser)
– Static assets: CSS, JS (speech recognition UI), images (src/public)
– EJS views & partials (src/views)
b. Backend (Express)
– Entry point: src/index.js & src/app.js
– Middleware: Helmet, bodyParser, Passport.js, connect-flash, custom error handlers
– Routes (src/routes) → Controllers (src/controllers) → Handlers (src/handlers) → Models (src/models)
– Validation: src/validators/validators.js
c. Database
– MongoDB via Mongoose schemas (user, run, note)
d. External / Browser APIs
– Passport.js (auth)
– WebKit SpeechRecognition (client-side speech-to-text)

##### Relationships & data flow
- Browser → HTTP requests (form or AJAX) → Express routes
- Routes → Controllers → Business logic (handlers/validators)
- Controllers → Mongoose models → MongoDB
- Controllers → render EJS views or redirect back → Browser
- Browser’s mic button leverages Web Speech API → sends text to server

##### Architectural patterns & principles
- MVC-style separation: Routes (entry), Controllers (coordination), Models (data)
- Middleware pipeline for auth, error handling, sanitization
- RESTful endpoints for CRUD on runs and notes
- Server-side rendering (no SPA) with progressive enhancement for speech input

##### Final checklist
- Clear labels (module names, file paths if desired)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Browser / Frontend
  subgraph "Browser / Frontend"
    direction TB
    A1["SpeechRecognition UI<br/>(script.js)"]:::client
    A2["EJS Views & Partials<br/>(src/views/)"]:::client
    A3["Static Assets<br/>(styles.css, images/)"]:::client
    A1 -->|"speech-to-text"| A2
    A2 -->|"form / fetch"| B1
  end

  %% Server / Backend
  subgraph "Server / Backend: Node.js / Express"
    direction TB
    B1["Express Routes<br/>(router.js, noteRoutes.js,<br/>runRoutes.js, userRoutes.js, renderRoutes.js)"]:::server
    B2["Controllers<br/>(noteController.js,<br/>runController.js,<br/>userController.js,<br/>renderController.js)"]:::server
    B3["Business Logic Handlers<br/>(noteHandler.js,<br/>runHandler.js,<br/>userHandler.js)"]:::server
    B4["Input Validation<br/>(validators.js)"]:::server
    B5["Database Connection<br/>(connect.js)"]:::server
    B6["Entry Point & App Setup<br/>(index.js, app.js)"]:::server
    B7["Auth Config<br/>(passport.js, auth.js)"]:::server
    B8["Middleware & Error Handling<br/>(errorHandlers.js,<br/>Helmet, bodyParser,<br/>connect-flash)"]:::server
    B1 --> B2
    B2 --> B3
    B3 --> B4
    B4 --> B5
    B2 --> C1
    B8 --> B1
    B7 --> B3
    B6 --> B1
  end

  %% Database
  subgraph "Database / MongoDB"
    direction TB
    C1["Mongoose Models<br/>(userSchema.js,<br/>runSchema.js,<br/>noteSchema.js)"]:::db
    C1 -->|"persist/retrieve"| C1
  end

  %% External / Browser APIs
  subgraph "External / APIs"
    direction TB
    D1["Web Speech API"]:::external
    D2["Passport.js"]:::external
    D3["connect-flash"]:::external
    D4["Helmet & bodyParser"]:::external
    D1 -.-> A1
    D2 -.-> B7
    D3 -.-> B8
    D4 -.-> B8
  end

  %% Data flows
  A3 -->|"loads assets"| A2
  C1 -->|"DB result"| B2
  B2 -->|"render view"| A2

  %% Click Events
  click A1 "https://github.com/kyrawest/runningthoughts/blob/main/src/public/script.js"
  click A3 "https://github.com/kyrawest/runningthoughts/blob/main/src/public/styles.css"
  click A3 "https://github.com/kyrawest/runningthoughts/tree/main/src/public/images/"
  click A2 "https://github.com/kyrawest/runningthoughts/tree/main/src/views/"
  click B6 "https://github.com/kyrawest/runningthoughts/blob/main/src/index.js"
  click B6 "https://github.com/kyrawest/runningthoughts/blob/main/src/app.js"
  click B5 "https://github.com/kyrawest/runningthoughts/blob/main/src/connect.js"
  click B7 "https://github.com/kyrawest/runningthoughts/blob/main/src/handlers/passport.js"
  click B7 "https://github.com/kyrawest/runningthoughts/blob/main/src/auth/auth.js"
  click B8 "https://github.com/kyrawest/runningthoughts/blob/main/src/handlers/errorHandlers.js"
  click B1 "https://github.com/kyrawest/runningthoughts/blob/main/src/routes/router.js"
  click B1 "https://github.com/kyrawest/runningthoughts/blob/main/src/routes/noteRoutes.js"
  click B1 "https://github.com/kyrawest/runningthoughts/blob/main/src/routes/runRoutes.js"
  click B1 "https://github.com/kyrawest/runningthoughts/blob/main/src/routes/userRoutes.js"
  click B1 "https://github.com/kyrawest/runningthoughts/blob/main/src/routes/renderRoutes.js"
  click B2 "https://github.com/kyrawest/runningthoughts/blob/main/src/controllers/noteController.js"
  click B2 "https://github.com/kyrawest/runningthoughts/blob/main/src/controllers/runController.js"
  click B2 "https://github.com/kyrawest/runningthoughts/blob/main/src/controllers/userController.js"
  click B2 "https://github.com/kyrawest/runningthoughts/blob/main/src/controllers/renderController.js"
  click B3 "https://github.com/kyrawest/runningthoughts/blob/main/src/handlers/noteHandler.js"
  click B3 "https://github.com/kyrawest/runningthoughts/blob/main/src/handlers/runHandler.js"
  click B3 "https://github.com/kyrawest/runningthoughts/blob/main/src/handlers/userHandler.js"
  click B4 "https://github.com/kyrawest/runningthoughts/blob/main/src/validators/validators.js"
  click C1 "https://github.com/kyrawest/runningthoughts/blob/main/src/models/userSchema.js"
  click C1 "https://github.com/kyrawest/runningthoughts/blob/main/src/models/runSchema.js"
  click C1 "https://github.com/kyrawest/runningthoughts/blob/main/src/models/noteSchema.js"

  %% Styles
  classDef client fill:#D0E8FF,stroke:#3B83BD;
  classDef server fill:#D0FFD6,stroke:#57A65A;
  classDef db fill:#FFE2AA,stroke:#E08F3C;
  classDef external fill:#F0F0F0,stroke:#999999,stroke-dasharray: 2 2;
```
