# ceas-ambassadors/ceas-ambassadors-website architecture

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

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

## Overview

1. **Overall shape**
   - This is a server-rendered **Node.js web application** for the CEAS Ambassadors organization.
   - It follows a fairly classic **Express MVC** structure: HTTP routes call controllers, controllers use models, and views are rendered with Pug templates.

2. **Request entrypoint and runtime**
   - `bin/www` is the executable entrypoint used to start the HTTP server.
   - `app.js` wires together the Express app, middleware, route registration, error handling, and static file serving.
   - The app is deployed as a typical Node service, with `procfile` indicating a process-managed runtime.

3. **Presentation layer**
   - The UI is generated on the server with **Pug** templates in `views/`.
   - Shared layout and reusable fragments live in `views/layout.pug` and `views/partials/`.
   - Feature-specific page sets are organized by domain: `views/event/`, `views/member/`, plus standalone pages like `calendar.pug`, `apply.pug`, `training.pug`, and `virtual-tour.pug`.

4. **Routing boundary**
   - Route modules in `routes/` split the web surface into three main areas:
     - `routes/index.js` for general site pages
     - `routes/event.js` for tour/event functionality
     - `routes/member.js` for member-related flows
   - These route modules are the HTTP boundary between incoming requests and business logic.

5. **Controller layer**
   - `controllers/` contains the application logic for each domain area:
     - `controllers/index.js`
     - `controllers/event.js`
     - `controllers/member.js`
   - Controllers orchestrate reads/writes and decide which view to render, keeping route handlers thin.

6. **Domain and persistence layer**
   - `models/` contains the data access and domain objects:
     - `event.js`
     - `member.js`
     - `attendance.js`
     - `session.js`
     - `index.js` as the model bootstrap/aggregation point
   - The repository docs indicate a **MySQL-backed database**, with schema details in `docs/database.md`.
   - `migrations/` contains schema evolution support, including a one-time upgrade script from `1.x.x` to `2.0.0`.

7. **Main business domains**
   - The app centers on three operational workflows:
     - **Event/tour management**: listing, creating, and viewing tours/events
     - **Member management**: profiles, signup/login, settings, and admin-style lists
     - **Attendance/progress tracking**: members sign up for tours and track requirements/points/status
   - Views like `event/detail`, `event/list`, `member/profile`, `member/points-table`, and `attendanceStatus` show these are first-class concepts.

8. **Authentication and session state**
   - `models/session.js` suggests persistent or structured session handling for logged-in users.
   - Member flows include `login`, `signup`, `reset`, and `settings`, so the system likely maintains authenticated user state across requests.
   - This is an important boundary for the architecture diagram: some routes are public, while member/admin actions depend on session context.

9. **Static assets and public content**
   - `public/` contains the client-facing static assets: stylesheets and images.
   - `public/stylesheets/style.css` is the primary visible styling hook.
   - These assets are served directly by the Express app rather than through the controller/model stack.

10. **Operational and maintenance tooling**
   - `docs/` contains the repo’s operational knowledge:
     - `dev-guide.md` for local setup
     - `production.md` for server management
     - `database.md` for schema and MySQL connectivity
   - `tools/db_backup.sh` indicates a maintenance workflow for backing up the database.

11. **Testing and verification**
   - `test/` includes coverage for the main functional areas: `account`, `attendance`, `event`, `member`, and basic app behavior.
   - CI is set up through GitHub Actions (`.github/workflows/project.yml`) and legacy Travis config (`.travis.yml`), showing the repository expects automated validation on change.

12. **External dependencies and integration points**
   - The key external dependency is the **MySQL database**.
   - The site is intended for the University of Cincinnati CEAS Ambassadors program, but the main architectural boundary is internal: browser users interact with the server-rendered app, which persists operational data in MySQL.

13. **How data typically flows**
   - A browser request hits Express → a route module selects a controller action → the controller reads/writes through a model → the model talks to MySQL → the controller renders a Pug view with returned data → HTML is sent back to the browser.
   - Static content bypasses this flow and is served from `public/`.

14. **What to emphasize in an architecture diagram**
   - Draw four main layers: **web client**, **Express app (routes/controllers)**, **domain/data models**, and **MySQL database**.
   - Show the **Pug view renderer** as part of the server-side presentation layer.
   - Include the separate operational path for **migrations/backups/docs/tests**, since these support the system but are not part of runtime request handling.

Main entry points: [`app.js`](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/app.js) (App), [`views`](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views) (Views), [`controllers/event.js`](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/controllers/event.js) (Event ctrl), [`controllers/member.js`](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/controllers/member.js) (Member ctrl)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_procfile["Procfile<br/>runtime hint"]
  node_www["www<br/>server entry"]
  node_app["App<br/>[app.js]"]
  node_config["Config<br/>settings<br/>[config.js]"]
end

subgraph group_presentation["Presentation"]
  node_views["Views<br/>pug templates"]
  node_layout["Layout<br/>[layout.pug]"]
  node_partials["Partials<br/>pug fragments"]
  node_event_views["Event pages<br/>pug pages"]
  node_member_views["Member pages<br/>pug pages"]
  node_static["Public assets<br/>static files"]
end

subgraph group_domain["Domain"]
  node_routes["Routes<br/>http boundary"]
  node_route_index["Site routes<br/>route module<br/>[index.js]"]
  node_route_event["Event routes<br/>route module<br/>[event.js]"]
  node_route_member["Member routes<br/>route module<br/>[member.js]"]
  node_controllers["Controllers<br/>application logic"]
  node_ctrl_index["Site ctrl<br/>controller<br/>[index.js]"]
  node_ctrl_event["Event ctrl<br/>controller<br/>[event.js]"]
  node_ctrl_member["Member ctrl<br/>controller<br/>[member.js]"]
  node_models[("Models<br/>data layer")]
  node_model_index["Model index<br/>bootstrap<br/>[index.js]"]
  node_model_event["Event model<br/>[event.js]"]
  node_model_member["Member model<br/>[member.js]"]
  node_model_attendance["Attendance<br/>model<br/>[attendance.js]"]
  node_model_session["Session model<br/>[session.js]"]
end

subgraph group_ops["Operations"]
  node_migrations["Migrations<br/>schema changes"]
  node_docs["Docs<br/>documentation"]
  node_tests["Tests<br/>verification"]
  node_backup["Backup tool<br/>maintenance<br/>[db_backup.sh]"]
  node_ci["CI<br/>automation"]
end

node_browser(("Browser<br/>client"))
node_mysql[("MySQL<br/>database")]

node_browser -->|"HTTP requests"| node_app
node_procfile -->|"start command"| node_www
node_www -->|"boot"| node_app
node_app -->|"registers"| node_routes
node_app -->|"serves"| node_static
node_app -->|"renders"| node_views
node_app -->|"loads"| node_config
node_routes -->|"includes"| node_route_index
node_routes -->|"includes"| node_route_event
node_routes -->|"includes"| node_route_member
node_route_index -->|"delegates to"| node_ctrl_index
node_route_event -->|"delegates to"| node_ctrl_event
node_route_member -->|"delegates to"| node_ctrl_member
node_controllers -->|"includes"| node_ctrl_index
node_controllers -->|"includes"| node_ctrl_event
node_controllers -->|"includes"| node_ctrl_member
node_ctrl_index -->|"renders pages"| node_views
node_ctrl_event -->|"renders pages"| node_event_views
node_ctrl_member -->|"renders pages"| node_member_views
node_ctrl_event -->|"uses"| node_model_event
node_ctrl_event -->|"uses"| node_model_attendance
node_ctrl_member -->|"uses"| node_model_member
node_ctrl_member -->|"uses"| node_model_session
node_ctrl_index -->|"uses"| node_model_index
node_model_index -->|"aggregates"| node_models
node_models -->|"includes"| node_model_event
node_models -->|"includes"| node_model_member
node_models -->|"includes"| node_model_attendance
node_models -->|"includes"| node_model_session
node_model_event -->|"persists to"| node_mysql
node_model_member -->|"persists to"| node_mysql
node_model_attendance -->|"persists to"| node_mysql
node_model_session -->|"persists to"| node_mysql
node_views -->|"shared shell"| node_layout
node_views -->|"shared fragments"| node_partials
node_views -->|"feature pages"| node_event_views
node_views -->|"feature pages"| node_member_views
node_docs -.->|"supports"| node_migrations
node_tests -.->|"verifies"| node_controllers
node_ci -.->|"runs"| node_tests
node_backup -.->|"backs up"| node_mysql

click node_procfile "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/procfile"
click node_www "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/bin/www"
click node_app "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/app.js"
click node_config "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/config/config.js"
click node_route_index "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/routes/index.js"
click node_route_event "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/routes/event.js"
click node_route_member "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/routes/member.js"
click node_ctrl_index "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/controllers/index.js"
click node_ctrl_event "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/controllers/event.js"
click node_ctrl_member "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/controllers/member.js"
click node_model_index "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/index.js"
click node_model_event "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/event.js"
click node_model_member "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/member.js"
click node_model_attendance "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/attendance.js"
click node_model_session "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/session.js"
click node_views "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views"
click node_layout "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/views/layout.pug"
click node_partials "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views/partials"
click node_event_views "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views/event"
click node_member_views "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views/member"
click node_static "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/public"
click node_migrations "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/migrations"
click node_docs "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/docs"
click node_tests "https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/test"
click node_backup "https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/tools/db_backup.sh"

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_procfile,node_www,node_app,node_config toneBlue
class node_views,node_layout,node_partials,node_event_views,node_member_views,node_static toneAmber
class node_routes,node_route_index,node_route_event,node_route_member,node_controllers,node_ctrl_index,node_ctrl_event,node_ctrl_member,node_models,node_model_index,node_model_event,node_model_member,node_model_attendance,node_model_session toneMint
class node_migrations,node_docs,node_tests,node_backup,node_ci toneRose
class node_browser,node_mysql toneNeutral
```

## Components

### Runtime

Server startup and request handling

- [Procfile](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/procfile): runtime hint · Process-managed deployment command · `procfile`
- [www](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/bin/www): server entry · Executable HTTP server entrypoint · `bin/www`
- [App](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/app.js): express app · Wires middleware, routes, static files, and errors · `app.js`
- [Config](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/config/config.js): settings · Application configuration values · `config/config.js`

### Presentation

Server-rendered pages and static assets

- [Views](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views): pug templates · Server-rendered pages and shared fragments · `views`
- [Layout](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/views/layout.pug): pug layout · Shared page shell · `views/layout.pug`
- [Partials](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views/partials): pug fragments · Reusable UI fragments · `views/partials`
- [Event pages](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views/event): pug pages · Event listing, detail, create, and attendance pages · `views/event`
- [Member pages](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/views/member): pug pages · Login, signup, profile, and settings pages · `views/member`
- [Public assets](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/public): static files · CSS and images served directly by Express · `public`

### Domain

Routes, controllers, and models

- **Routes**: http boundary · Request routing for site areas
- [Site routes](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/routes/index.js): route module · General pages and shared site surface · `routes/index.js`
- [Event routes](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/routes/event.js): route module · Tour and event request handling · `routes/event.js`
- [Member routes](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/routes/member.js): route module · Member account request handling · `routes/member.js`
- **Controllers**: application logic · Orchestrate domain actions and view selection
- [Site ctrl](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/controllers/index.js): controller · General page actions · `controllers/index.js`
- [Event ctrl](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/controllers/event.js): controller · Event and attendance actions · `controllers/event.js`
- [Member ctrl](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/controllers/member.js): controller · Member account and profile actions · `controllers/member.js`
- **Models**: data layer · Domain objects and persistence access
- [Model index](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/index.js): bootstrap · Model aggregation and initialization · `models/index.js`
- [Event model](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/event.js): model · Event and tour data access · `models/event.js`
- [Member model](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/member.js): model · Member account data access · `models/member.js`
- [Attendance](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/attendance.js): model · Signups, points, and attendance tracking · `models/attendance.js`
- [Session model](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/models/session.js): model · Logged-in session state management · `models/session.js`

### Operations

Docs, tests, migrations, and maintenance

- [Migrations](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/migrations): schema changes · Database upgrade scripts and migration notes · `migrations`
- [Docs](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/docs): documentation · Development, production, and database guidance · `docs`
- [Tests](https://github.com/ceas-ambassadors/ceas-ambassadors-website/tree/master/test): verification · Functional coverage for app, account, event, member, and attendance · `test`
- [Backup tool](https://github.com/ceas-ambassadors/ceas-ambassadors-website/blob/master/tools/db_backup.sh): maintenance · Database backup script · `tools/db_backup.sh`
- **CI**: automation · GitHub Actions and legacy Travis validation

### Other components

- **Browser**: client · End users accessing the site
- **MySQL**: database · Persistent backend database

## Connections

- Browser → App: HTTP requests · Browser traffic enters the Express application
- Procfile → www: start command · Process manager launches the server entrypoint
- www → App: boot · Server entrypoint initializes the Express app
- App → Routes: registers · Express mounts the route modules
- App → Public assets: serves · Static files bypass controller logic
- App → Views: renders · View engine produces HTML responses
- App → Config: loads · Application behavior is configured from settings
- Routes → Site routes: includes · General site routing
- Routes → Event routes: includes · Event and tour routing
- Routes → Member routes: includes · Member account routing
- Site routes → Site ctrl: delegates to · Route handlers call site controller actions
- Event routes → Event ctrl: delegates to · Route handlers call event controller actions
- Member routes → Member ctrl: delegates to · Route handlers call member controller actions
- Controllers → Site ctrl: includes · Site controller module
- Controllers → Event ctrl: includes · Event controller module
- Controllers → Member ctrl: includes · Member controller module
- Site ctrl → Views: renders pages · General pages are rendered through Pug templates
- Event ctrl → Event pages: renders pages · Event workflows render event templates
- Member ctrl → Member pages: renders pages · Member workflows render member templates
- Event ctrl → Event model: uses · Event actions read and write event data
- Event ctrl → Attendance: uses · Attendance and signup logic
- Member ctrl → Member model: uses · Member actions read and write member data
- Member ctrl → Session model: uses · Authentication and session state
- Site ctrl → Model index: uses · Shared model initialization and access
- Model index → Models: aggregates · Model bootstrap groups persistence components
- Models → Event model: includes · Event persistence layer
- Models → Member model: includes · Member persistence layer
- Models → Attendance: includes · Attendance persistence layer
- Models → Session model: includes · Session persistence layer
- Event model → MySQL: persists to · Event data stored in MySQL
- Member model → MySQL: persists to · Member data stored in MySQL
- Attendance → MySQL: persists to · Attendance data stored in MySQL
- Session model → MySQL: persists to · Session state stored in MySQL
- Views → Layout: shared shell · Common page layout
- Views → Partials: shared fragments · Reusable UI partials
- Views → Event pages: feature pages · Event-related templates
- Views → Member pages: feature pages · Member-related templates
- Docs → Migrations: supports · Documentation describes schema evolution and operations
- Tests → Controllers: verifies · Tests cover major application workflows
- CI → Tests: runs · Automation executes repository validation
- Backup tool → MySQL: backs up · Maintenance script targets the database
